openapi: 3.0.1
info:
title: Cart Actions Endpoints Customer Profile API
description: fabric's **Cart API** lets you add, update, and remove items from your Storefront cart, either as a guest user or as a logged-in user. It also provides functionality to merge carts when you switch from guest user to logged-in user, and apply coupons and other attributes (for example, gift wrapping) to the line items. Additionally, the API supports more advanced tasks such as using multiple carts within a B2B organization, sharing carts, and supporting a unified cart experience for multi-region and multi-brand businesses.<p>The Cart API provides high performance, scalability, multi-tenancy, and configurability to the end-to-end order processing actions that start from the item being added to the cart; through the pre-checkout stage that includes billing, shipping, and payment details; to the checkout stage where the order is processed and confirmed by fabric's Order Management System (OMS)
contact:
name: Cart Support
email: support.cnc@fabric.inc
license:
name: fabric API License
url: https://fabric.inc/api-license
version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
security:
- bearerAuth: []
tags:
- name: Customer Profile
description: These endpoints provide the features for store admins to create and manage customers' details.
paths:
/Customers:
post:
tags:
- Customer Profile
summary: Add a New Customer
description: Using this endpoint, you can add a new customer to the system. The response includes an `id` which is required in subsequent calls, such as `GET /customers/{customerId}`, `PUT /customers/{customerId}`, `PATCH /customers/{customerId}`, and more. <br /> When `externalId` is specified, the customers have the ability to manage their own details through the storefront UI.
operationId: createCustomer
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
description: A sample request to add a new customer.
content:
application/json:
schema:
$ref: '#/components/schemas/createCustomerRequest'
required: true
responses:
'201':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/createCustomerResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
get:
tags:
- Customer Profile
summary: Get Customers
description: Use this endpoint to get a paginated list of customers. <br /> By specifying the query parameters `offset` and `limit`, you can narrow down the search results. You can also `sort` the results in an ascending or descending order. Additionally, with the `isDeleted` query parameter, you can filter for either deleted or non-deleted customers. When no query parameter is specified, by default, you get up to 10 records.
operationId: listCustomers
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
- name: offset
in: query
description: The number of records to skip before returning records. For example, when offset is 20 and limit's 10, this endpoint returns records from 21 to 30.
style: form
explode: true
schema:
type: integer
format: int32
example: 0
default: 0
- name: limit
in: query
required: false
description: The maximum number of records in a single page.
style: form
explode: true
schema:
type: integer
format: int32
example: 2
default: 10
- name: sort
in: query
description: The criteria to sort results, where `-` indicates a descending order and `+` indicates an ascending order. You can apply sorting to the following fields - `createdAt`, `updatedAt`, `firstName`, `lastName`, `emailAddress` and `status`.
required: false
style: form
explode: true
schema:
type: string
example: -updatedAt
- name: isDeleted
in: query
required: false
description: A flag indicating whether only the deleted customers need to be included. Set to `true` to include only the deleted customers and `false` to exclude deleted customers.
style: form
explode: true
schema:
type: boolean
example: false
enum:
- false
- true
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/listCustomerResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/customers/{customerId}:
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
- $ref: '#/components/parameters/customerIdPathParam'
get:
tags:
- Customer Profile
summary: Get Customer Details
description: Using this endpoint, you can get details of a single customer by `customerId`.
operationId: getCustomer
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
put:
tags:
- Customer Profile
summary: Update Customer Details
description: Using this endpoint, you can update details of an existing customer by `customerId`. <br /> This endpoint replaces the existing details of the customer. If you want to make only a partial update, without replacing the entire details, use the `PATCH /customers/{customerId}` endpoint.
operationId: updateCustomer
requestBody:
description: body request
content:
application/json:
schema:
$ref: '#/components/schemas/updateCustomerRequest'
required: true
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
patch:
tags:
- Customer Profile
summary: Partially Update Customer Details
description: Using this endpoint, you can partially update details of a customer by `customerId`. To fully replace the details of an existing customer, use the `PUT /customers/{customerId}` endpoint.
operationId: updateSpecifcDetailsOfCustomer
requestBody:
description: A sample request to partially update customer details.
content:
application/json:
schema:
$ref: '#/components/schemas/updateCustomerRequest'
required: true
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
delete:
tags:
- Customer Profile
summary: Delete Customer
description: With this endpoint, you can delete an existing customer data by `customerId`.
operationId: deleteCustomer
responses:
'200':
$ref: '#/components/responses/deleteCustomerResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
/customers/{customerId}/actions/update-status:
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
- $ref: '#/components/parameters/customerIdPathParam'
post:
tags:
- Customer Profile
summary: Update Customer Status
description: With this endpoint, you can update the account status of an existing customer by `customerId`.
operationId: updateCustomerStatus
requestBody:
description: A sample request to update customer's account status.
content:
application/json:
schema:
$ref: '#/components/schemas/updateCustomerStatusRequest'
responses:
'200':
$ref: '#/components/responses/customerStatusUpdateResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
/customers/search:
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
post:
tags:
- Customer Profile
summary: Search for Customer
description: Using this endpoint, you can search for customers based on filter conditions. By specifying `offset` and `limit`, you can narrow down your search results. In addition, using the `isDelete` property in the request body, you can filter for either deleted or non-deleted customers.
operationId: searchCustomer
requestBody:
description: A sample request to search for customers.
content:
application/json:
schema:
$ref: '#/components/schemas/customerSearchRequest'
required: true
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/listCustomerResponse'
'400':
$ref: '#/components/responses/searchBadRequest'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
components:
responses:
internalServerError:
description: The request is received but an internal error occurred
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/message'
example:
type: INTERNAL_SERVER_ERROR
message: Internal server error
forbidden:
description: Forbidden Request
headers:
x-fabric-request-id:
description: Unique request ID
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
content:
application/json:
schema:
$ref: '#/components/schemas/message'
example:
type: REQUEST_DENIED
message: Forbidden
customerStatusUpdateResponse:
description: Customer status update response
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/customerStatusUpdate'
examples:
customerStatusUpdateSuccess:
value:
type: CUSTOMER_STATUS_UPDATE_SUCCESS
message: Customer status updated successfully
status: ACTIVE
customerStatusAlreadyUpdated:
value:
type: CUSTOMER_STATUS_ALREADY_UPDATED
message: Customer already has the target status
status: ACTIVE
badRequest:
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/message'
examples:
invalidAccountProvided:
value:
type: INVALID_ACCOUNT_PROVIDED
message: Invalid account provided for the request.
deleteCustomerResponse:
description: Delete customer response
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/message'
examples:
customerDeletionSuccess:
value:
type: CUSTOMER_DELETED_SUCCESSFULLY
message: Customer deleted successfully
customerDeletedAlready:
value:
type: CUSTOMER_DELETED_SUCCESSFULLY
message: Customer already deleted
customerNotFound:
description: The resource isn't found
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/message'
example:
type: CUSTOMER_NOT_FOUND
message: Data with the given identifier isn't found
searchBadRequest:
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/message'
examples:
invalidAccountProvided:
value:
type: INVALID_ACCOUNT_PROVIDED
message: Invalid account provided for the request.
invalidSearchOperation:
value:
type: INVALID_SEARCH_OPERATION
schemas:
customerStatusUpdate:
description: The details of customer's status.
type: object
properties:
type:
description: A machine-readable code.
type: string
example: SUCCESS
message:
description: A human-readable message corresponding to `type`.
type: string
example: Success message
status:
description: The customer's account status.
type: string
enum:
- ACTIVE
- INACTIVE
- BLOCKED
example: ACTIVE
required:
- type
- message
listCustomerResponse:
description: The list of customers.
type: object
properties:
query:
$ref: '#/components/schemas/Query'
data:
type: array
items:
$ref: '#/components/schemas/createCustomerResponse'
customerAddressResponse:
required:
- id
- address
- isDeleted
- createdAt
- updatedAt
type: object
properties:
id:
type: string
description: A 24-character system-generated ID of the address.
example: 61604a30fdfacd0009816e44
uniqueItems: true
address:
$ref: '#/components/schemas/commonAddress'
additionalAttributes:
description: A placeholder for additional info, in key-value pairs.
type: object
example:
landmark: Beach
isDeleted:
type: boolean
description: A flag indicating whether the address is deleted. `true` indicates the address is deleted and `false` indicates otherwise.
example: false
isDefault:
description: A flag indicating whether the address is the default one.`true` indicates the given address is the default address and `false` indicates otherwise.
type: boolean
example: false
deletedAt:
description: The time when the address was deleted, in UTC format.
type: string
format: date-time
example: '2023-08-30T23:20:42.822Z'
nullable: true
createdAt:
description: The time when the address was created, in UTC format.
type: string
format: date-time
example: '2023-08-30T23:20:42.822Z'
updatedAt:
description: The time when the address was the last updated, in UTC format.
type: string
format: date-time
example: '2023-08-30T23:20:42.822Z'
nullable: true
searchIsDeleted:
type: boolean
description: A flag indicating whether the search results should include only deleted addresses. Set to `true` to include only deleted addresses and `false` to exclude deleted addresses.
enum:
- false
- true
example: false
searchEmailAddress:
type: object
description: The criteria to search for customers based on their email.
properties:
op:
type: string
description: The type of search operation. Multiple values, separated by commas, can be used for the IN and NOT_IN operations, while only a single value can be used for the EQUALS, CONTAINS, and NOT_EQUALS operations.
enum:
- IN
- NOT_IN
- EQUALS
- CONTAINS
- NOT_EQUALS
example: IN
value:
type: string
description: The customer's email address.
example: pat.kake@example.com
required:
- op
- value
customerMatch:
type: object
description: The criteria to search for customers.
properties:
id:
$ref: '#/components/schemas/searchId'
firstName:
$ref: '#/components/schemas/searchFirstName'
lastName:
$ref: '#/components/schemas/searchLastName'
emailAddress:
$ref: '#/components/schemas/searchEmailAddress'
externalId:
$ref: '#/components/schemas/searchExternalId'
createdAt:
$ref: '#/components/schemas/searchCreatedAt'
updatedAt:
$ref: '#/components/schemas/searchUpdatedAt'
deletedAt:
$ref: '#/components/schemas/searchDeletedAt'
status:
$ref: '#/components/schemas/searchStatus'
additionalAttributes:
$ref: '#/components/schemas/searchAdditionalAttribute'
isDeleted:
$ref: '#/components/schemas/searchIsDeleted'
searchAdditionalAttribute:
type: object
description: The criteria to search for customers or their addresses based on additional attributes.
properties:
key:
type: string
description: The key for the additional attribute. This should be the field name given in the `additionalAttributes` schema.
example: gps
anyOf:
- $ref: '#/components/schemas/searchStringOperation'
- $ref: '#/components/schemas/searchNumberOrDateOperation'
required:
- key
- op
searchNumberOrDateOperation:
type: object
description: The criteria to search for records by number, date, range of numbers, or range of dates.
properties:
op:
type: string
description: The type of search operation, such as equals, less than (LT), greater than (GT), less than or equal to (LTE), greater than or equal to (GTE), or within a specified range.
enum:
- EQUALS
- LTE
- GTE
- GT
- LT
- RANGE
example: LTE
value:
type: string
description: The value of the number or the date.
example: '2023-08-30T23:20:42.822Z'
fromValue:
type: string
description: The starting value of the number or date range. This is used with the `toValue` property.
example: '2023-08-30T23:20:42.822Z'
toValue:
type: string
description: The ending value of the number or date range. This is used with the `fromValue` property.
example: '2023-08-31T23:20:42.822Z'
example:
op: LTE
value: '2023-08-30T23:20:42.822Z'
searchFirstName:
type: object
description: The criteria to search for customers based on their first name.
properties:
op:
type: string
description: The type of search operation. Multiple values, separated by commas, can be used for the IN and NOT_IN operations, while only a single value can be used for the EQUALS, CONTAINS, and NOT_EQUALS operations.
enum:
- IN
- NOT_IN
- EQUALS
- CONTAINS
- NOT_EQUALS
example: IN
value:
type: string
description: The customer's first name.
example: Pat
required:
- op
- value
message:
description: The response message.
type: object
properties:
type:
description: A machine-readable code.
type: string
example: SUCCESS
message:
description: A human-friendly message corresponding to the `type`.
type: string
example: Success message
required:
- type
- message
createCustomerResponse:
required:
- id
- isDeleted
- createdAt
- updatedAt
- name
- emailAddress
type: object
properties:
id:
type: string
description: A 24-character system-generated customer ID.
uniqueItems: true
example: 61df41892bf06d00092d0d8a
name:
$ref: '#/components/schemas/commonName'
status:
description: The status of the customer.
type: string
enum:
- ACTIVE
- INACTIVE
- BLOCKED
example: ACTIVE
emailAddress:
type: string
description: The customer's email.
format: email
example: test@example.com
phone:
$ref: '#/components/schemas/phone'
externalId:
type: string
description: A UUID of the customer.
example: 1231012312-312-31231asda
additionalAttributes:
description: A placeholder for additional info, in key-value pairs.
type: object
example:
middleName: user
isDeleted:
type: boolean
description: A flag indicating whether the customer data is deleted. `true` indicates the customer data is deleted and `false` indicates otherwise.
example: false
deletedAt:
description: The time when the customer data was deleted, in UTC format.
type: string
format: date-time
example: '2023-08-30T23:20:42.822Z'
nullable: true
createdAt:
description: The time when the customer was added, in UTC format.
type: string
format: date-time
example: '2023-08-30T23:20:42.822Z'
updatedAt:
description: The time when the customer details were last updated, in UTC format.
type: string
format: date-time
example: '2023-08-30T23:20:42.822Z'
nullable: true
commonName:
type: object
description: The full name of the customer.
required:
- firstName
- lastName
properties:
title:
description: The customer's title, such as Mr., Mrs, and Dr.
type: string
example: Dr.
firstName:
description: The customer's first name.
type: string
example: Pat
middleName:
description: The customer's middle name.
type: string
example: E
lastName:
description: The customer's last name.
type: string
example: Doe
suffix:
description: The suffix for the customer's name, such as Jr., PhD, and more.
type: string
example: Jr.
searchId:
type: object
description: A unique identifier of the search criteria.
properties:
op:
type: string
enum:
- IN
- EQUALS
description: The type of search operation.
example: IN
value:
type: string
description: A 24-character system-generated ID of the given search criteria.
example: 61df41892bf06d00092d0d8a
required:
- op
- value
createCustomerRequest:
type: object
required:
- name
- emailAddress
properties:
name:
$ref: '#/components/schemas/commonName'
emailAddress:
type: string
description: The customer's email.
format: email
example: test@example.com
phone:
$ref: '#/components/schemas/phone'
externalId:
type: string
description: A UUID of the customer.
example: 1231012312-312-31231asda
additionalAttributes:
description: A placeholder for additional info, in key-value pairs.
type: object
example:
type: shopper
commonAddress:
type: object
description: The address details.
required:
- type
properties:
addressLine1:
description: The first line of the address.
type: string
example: 123 Main St.
addressLine2:
description: The second line of the address.
type: string
example: Suite 100
addressLine3:
description: The third line of the address.
type: string
example: Seventh floor
addressLine4:
description: The fourth line of the address.
type: string
example: 'Attention: Pat E. Doe'
city:
description: The city name in the address.
type: string
example: Seattle
region:
description: The region or state name in the address.
type: string
example: WA
postalCode:
description: The postal or ZIP code of the address.
type: string
example: 98121
county:
description: The administrative division or county within a country or state.
type: string
example: King County
country:
description: The country code, which can be a full name, or an ISO 3166-1 alpha-2 or alpha-3 code.
type: string
example: US
type:
description: The address type.
type: string
enum:
- BILLING
- SHIPPING
example: BILLING
latitude:
description: The geographical `latitude` used with `longitude` to locate the exact address. The coordinates are provided in decimal degrees format, with negative values indicating locations to the west.
type: number
format: double
example: 47.6205
longitude:
description: The geographical `longitude` used with `latitude` to locate the exact address. The coordinates are provided in decimal degrees format, with negative values indicating locations to the west.
type: number
format: double
example: -122.3493
Query:
type: object
description: The pagination criteria.
properties:
offset:
type: number
description: The number of records to skip before returning records. For example, when offset is 20 and limit's 10, you get records from 21 to 30. When they're not specified, you get up to 10 records.
example: 0
limit:
type: number
description: The maximum number of records per page.
example: 20
count:
type: number
description: The total number of records in the response.
example: 100
updateCustomerStatusRequest:
type: object
properties:
status:
description: The status of the customer's account.
type: string
enum:
- ACTIVE
- INACTIVE
- BLOCKED
example: ACTIVE
searchLastName:
type: object
description: The criteria to search for customers based on their last name.
properties:
op:
type: string
description: The type of search operation. Multiple values, separated by commas, can be used for the IN and NOT_IN operations, while only a single value can be used for the EQUALS, CONTAINS, and NOT_EQUALS operations.
enum:
- IN
- NOT_IN
- EQUALS
- CONTAINS
- NOT_EQUALS
example: IN
value:
type: string
description: The customer's last name.
example: Kake
required:
- op
- value
updateCustomerRequest:
type: object
required:
- name
- emailAddress
properties:
name:
$ref: '#/components/schemas/updateCommonNameRequest'
emailAddress:
type: string
description: The customer's email.
format: email
example: test@example.com
phone:
$ref: '#/components/schemas/phone'
externalId:
type: string
description: A UUID of the customer.
example: 1231012312-312-31231asda
additionalAttributes:
description: A placeholder for additional info, in key-value pairs.
type: object
example:
middleName: user
searchCreatedAt:
type: object
description: The criteria to search for customers or their addresses based on a specific creation date or within a creation date range.
properties:
op:
type: string
description: The type of search operation, such as equals, less than (LT), greater than (GT), less than or equal to (LTE), greater than or equal to (GTE), or within a specified range.
enum:
- EQUALS
- LTE
- GTE
- GT
- LT
- RANGE
example: LTE
value:
type: string
description: The time of creation, in UTC format.
example: '2023-08-30T23:20:42.822Z'
startCreatedAt:
type: string
description: The starting value of the creation date range. This is used with the `endCreatedAt` property.
example: '2023-08-30T23:20:42.822Z'
endCreatedAt:
type: string
description: The ending value of the creation date range. This is used with the `startCreatedAt` property.
example: '2023-08-31T23:20:42.822Z'
example:
op: LTE
value: '2023-08-30T23:20:42.822Z'
required:
- op
customerSearchRequest:
type: object
description: The criteria to search for cust
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-customer-profile-api-openapi.yml