OpenAPI Specification
swagger: '2.0'
info:
version: '1.0'
title: NewStore address customer-profile API
description: NewStore public APIs
contact:
email: support@newstore.com
name: NewStore API Support
url: https://developer.newstore.com
host: dodici-demo.p.newstore.net
basePath: /
schemes:
- https
consumes:
- application/json
produces:
- application/json
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
produces:
- application/problem+json
- application/json
parameters:
- name: q
in: query
required: false
type: string
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.'
- name: sort
in: query
required: false
type: string
description: The sort to be applied to customers response.
- name: offset
in: query
required: false
default: 0
type: integer
format: int32
minimum: 0.0
exclusiveMinimum: false
description: The customer profiles page offset.
- name: count
in: query
required: false
default: 10
type: integer
format: int32
minimum: 1.0
maximum: 500.0
exclusiveMaximum: false
exclusiveMinimum: false
description: The number of requested customer profiles.
responses:
default:
description: Unexpected error
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: The list customer profiles response.
schema:
$ref: '#/definitions/ListProfilesResponse'
headers: {}
'400':
description: Bad Request.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal server error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
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
produces:
- application/problem+json
- application/json
consumes:
- application/json
parameters:
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: Request payload
schema:
$ref: '#/definitions/CreateProfileRequest'
responses:
default:
description: Unexpected error
schema:
$ref: '#/definitions/Problem'
headers: {}
'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.
schema:
$ref: '#/definitions/ProfileResponse'
headers: {}
'400':
description: Bad Request.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'422':
description: Unable to process the entity.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal server error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- customer:profile:write
/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
produces:
- application/problem+json
- application/json
parameters:
- name: profile_id
in: path
required: true
type: string
description: Profile ID
responses:
default:
description: Unexpected error
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: The customer profile response.
schema:
$ref: '#/definitions/ProfileResponse'
headers: {}
'400':
description: Bad Request.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Not Found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal server error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
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
produces:
- application/problem+json
- application/json
consumes:
- application/json
parameters:
- name: profile_id
in: path
required: true
type: string
description: Profile ID
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: Request payload
schema:
$ref: '#/definitions/UpdateProfileRequest'
responses:
default:
description: Unexpected error
schema:
$ref: '#/definitions/Problem'
headers: {}
'200':
description: The update customer profile response.
schema:
$ref: '#/definitions/ProfileResponse'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Profile not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'409':
description: 'Conflict response.
It happens when profile has a newer state, than given last_updated_at.'
schema:
$ref: '#/definitions/Problem'
headers: {}
'422':
description: Unable to process the entity.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal server error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- customer:profile:write
post:
description: Creates request for customer profile deletion.
summary: createProfileDeletionRequest
tags:
- customer-profile
operationId: createProfileDeletionRequest
deprecated: false
produces:
- application/problem+json
consumes:
- application/json
parameters:
- name: profile_id
in: path
required: true
type: string
description: Profile ID
- name: Content-Type
in: header
required: false
enum:
- application/json
type: string
description: ''
- name: body
in: body
required: true
description: Request payload
schema:
$ref: '#/definitions/ProfileDeletionRequest'
responses:
default:
description: Unexpected error
schema:
$ref: '#/definitions/Problem'
headers: {}
'202':
description: Deletion request accepted.
headers: {}
'400':
description: Bad Request.
schema:
$ref: '#/definitions/Problem'
headers: {}
'403':
description: Forbidden.
schema:
$ref: '#/definitions/Problem'
headers: {}
'404':
description: Profile not found.
schema:
$ref: '#/definitions/Problem'
headers: {}
'409':
description: Deletion already requested.
schema:
$ref: '#/definitions/Problem'
headers: {}
'429':
description: Too Many Requests
schema:
$ref: '#/definitions/Problem'
headers:
Retry-After:
type: string
'500':
description: Internal server error.
schema:
$ref: '#/definitions/Problem'
headers: {}
'502':
description: Bad Gateway
schema:
$ref: '#/definitions/Problem'
headers: {}
'503':
description: Service Unavailable
schema:
$ref: '#/definitions/Problem'
headers: {}
security:
- oauth:
- customer:profile:write
definitions:
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
maximum: 600.0
exclusiveMaximum: true
format: int32
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
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
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: '#/definitions/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
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: '#/definitions/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
ListProfilesResponse:
title: ListProfilesResponse
description: List profiles response.
type: object
properties:
pagination_info:
type: object
allOf:
- $ref: '#/definitions/PaginationInfo'
- description: Pagination info.
profiles:
type: array
items:
$ref: '#/definitions/ProfileResponse'
required:
- pagination_info
- profiles
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: '#/definitions/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
securityDefinitions:
oauth:
type: oauth2
flow: application
tokenUrl: https://id.p.newstore.net/auth/realms/dodici-demo/protocol/openid-connect/token
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