openapi: 3.0.0
info:
title: Customers
description: >-
The fabric **Customers** API is used to create and manage details of
storefront customers, also referred to as shoppers. The `Customers` or
`Customer Address` APIs provide features for store admins to manage their
customers' details and addresses. The `Customer Self' API provide features
for customers or shoppers to independently manage their own details.
version: 3.0.0
x-audience: external-public
contact:
name: fabric Support
email: [email protected]
license:
name: fabric API License
url: https://fabric.inc/api-license
termsOfService: https://fabric.inc/terms-of-use
servers:
- url: https://api.fabric.inc/v3
description: Production
tags:
- name: Customer Profile
description: >-
These endpoints provide the features for store admins to create and manage
customers' details.
- name: Customer Address
description: >-
These endpoints provide the features for store admins to create and manage
customers' addresses.
- name: Customer Self
description: >-
These endpoints provide the feature for customers or shoppers to
independently manage their details in the storefront.
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'
/customers/{customerId}/customer-address:
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
- $ref: '#/components/parameters/customerIdPathParam'
post:
tags:
- Customer Address
summary: Add a New Address
description: >-
Using this endpoint, you can add a new address for the customer by
`customerId`.
operationId: createCustomerAddress
requestBody:
description: A sample request to add customer's address.
content:
application/json:
schema:
$ref: '#/components/schemas/customerAddressRequest'
responses:
'201':
description: Created
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/customerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
get:
tags:
- Customer Address
summary: Get Customer's Addresses
description: >-
Using this endpoint, you can get all addresses of a customer. <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: listCustomersAddresses
parameters:
- 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.
required: false
style: form
explode: true
schema:
type: integer
format: int32
example: 0
default: 0
- name: limit
in: query
description: The maximum number of records per page.
required: false
style: form
explode: true
schema:
type: integer
format: int32
example: 10
default: 10
- name: sort
in: query
description: >-
The criteria to sort results, where `-` indicates a descending order
and `+` indicates an ascending order. You can sort the following
fields - `updatedAt`, `country`, `city`, and `region`.
required: false
style: form
explode: true
schema:
type: string
example: '-updatedAt'
- name: isDeleted
in: query
description: >-
A flag indicating whether only the deleted addresses must be
included in the response. Set to `true` to include only the deleted
addresses of the customers and `false` to exclude the deleted
addresses.
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/listCustomerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
/customers/{customerId}/customer-address/{addressId}:
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
- $ref: '#/components/parameters/customerIdPathParam'
- $ref: '#/components/parameters/addressIdPathParam'
get:
tags:
- Customer Address
summary: Get Customer's Address
description: >-
Using this endpoint, you can get a single address of a customer based on
the `customerId` and `addressId`.
operationId: getCustomersAddress
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/customerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerAddressNotFound'
'500':
$ref: '#/components/responses/internalServerError'
put:
tags:
- Customer Address
summary: Update Customer's Address
description: >-
Using this endpoint, you can update a customer's address based on the
`customerId` and `addressId`. This replaces the existing address with
the new one. If you want to make only a partial update, use the `PATCH
/customers/{customerId}/customer-address/{addressId}` endpoint.
operationId: updateAddressForCustomer
requestBody:
description: A sample request to update an address of a customer.
content:
application/json:
schema:
$ref: '#/components/schemas/updateCustomerAddressRequest'
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/customerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerAddressNotFound'
'500':
$ref: '#/components/responses/internalServerError'
patch:
tags:
- Customer Address
summary: Partially Update Customer's Address
description: >-
Using this endpoint, you can partially update a customer's address based
on the `customerId` and `addressId`. To fully replace an existing
address, use the `PUT
/customers/{customerId}/customer-address/{addressId}` endpoint.
operationId: updateSpecificDetailsOfAddressForCustomer
requestBody:
description: A sample request to partially update the customer's address.
content:
application/json:
schema:
$ref: '#/components/schemas/updateCustomerAddressRequest'
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/customerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerAddressNotFound'
'500':
$ref: '#/components/responses/internalServerError'
delete:
tags:
- Customer Address
summary: Delete Customer's Address
description: >-
Using this endpoint, you can delete an existing address of a customer
based on the `customerId` and `addressId`.
operationId: deleteCustomersAddress
responses:
'200':
$ref: '#/components/responses/deleteCustomerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerAddressNotFound'
'500':
$ref: '#/components/responses/internalServerError'
/customers/{customerId}/customer-address/search:
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
- $ref: '#/components/parameters/customerIdPathParam'
post:
tags:
- Customer Address
summary: Search for Customer's Addresses
description: >-
With this endpoint, you can search for customer's addresses based on the
specified filter conditions. In addition, you can tailor the search
results by including or excluding the deleted addresses and the default
addresses.<br />**Note**:A customer can have a default address for both
billing and shipping.
operationId: searchCustomerAddress
requestBody:
description: A sample request to search for the customer's addresses.
content:
application/json:
schema:
$ref: '#/components/schemas/customerAddressSearchRequest'
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/listCustomerAddressResponse'
'400':
$ref: '#/components/responses/searchBadRequest'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internalServerError'
/customers/self:
parameters:
- name: x-fabric-tenant-id
in: header
description: >-
A header used by fabric to identify the tenant making the request. You
must include tenant id in the authentication header for an API request
to access any of fabric’s endpoints. You can retrieve the tenant id ,
which is also called account id, from
[Copilot](/v3/platform/settings/account-details/getting-the-account-id).
This header is required.
schema:
type: string
example: 517fa9dfd42d8b00g1o3k312
- name: x-fabric-request-id
in: header
description: Unique request ID
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
required: false
get:
tags:
- Customer Self
summary: Get Customer Details - Customer Context
description: >-
Using this endpoint, a customer can view their details through the
storefront UI.
operationId: getCustomerSelf
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 Self
summary: Update Customer Details - Customer Context
description: >-
Using this endpoint, customers can update their own details through the
storefront UI.
operationId: updateCustomerSelf
requestBody:
description: A sample request to update customer's details.
content:
application/json:
schema:
$ref: '#/components/schemas/updateCustomerSelfRequest'
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'
/customers/self/customer-address:
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
get:
tags:
- Customer Self
summary: View Addresses - Customer Context
description: >-
Using this endpoint, a customer can view their own addresses through the
storefront UI.
operationId: listCustomersAddressSelf
parameters:
- 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.
required: false
style: form
explode: true
schema:
type: integer
format: int32
example: 0
- name: limit
in: query
description: The maximum number of records in a single page.
required: false
style: form
explode: true
schema:
type: integer
format: int32
example: 10
- name: sort
in: query
description: >-
The criteria to sort results, where `-` indicates a descending order
and `+` indicates an ascending order. You can sort the following
fields - `updatedAt`, `country`, `city`, and `region`.
required: false
style: form
explode: true
schema:
type: string
example: '-updatedAt'
default: '-updatedAt'
- name: isDeleted
in: query
description: >-
A flag indicating whether only the deleted addresses are returned in
the response. Specify `true` to get only the deleted addresses and
`false` to get only the non-deleted ones.
style: form
explode: true
schema:
type: boolean
default: false
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/listCustomerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
post:
tags:
- Customer Self
summary: Add Address - Customer Context.
description: >-
Using this endpoint, a customer can add their address through a
storefront UI.
operationId: createCustomerAddressSelf
requestBody:
description: A sample request body to add address.
content:
application/json:
schema:
$ref: '#/components/schemas/customerAddressRequest'
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/customerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerNotFound'
'500':
$ref: '#/components/responses/internalServerError'
/customers/self/customer-address/{addressId}:
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricRequestId'
- $ref: '#/components/parameters/addressIdPathParam'
get:
tags:
- Customer Self
summary: View Address - Customer Context
description: >-
Using this endpoint, a customer can view their own address through the
storefront UI based on the `addressId`.
operationId: getAddressForCustomerSelf
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/customerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerAddressNotFound'
'500':
$ref: '#/components/responses/internalServerError'
put:
tags:
- Customer Self
summary: Update Address - Customer Context
description: >-
Using this endpoint, a customer can update their own address through the
storefront UI based on `addressId`.
operationId: updateAddressForCustomerSelf
requestBody:
description: A sample request for update address.
content:
application/json:
schema:
$ref: '#/components/schemas/customerAddressRequest'
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/customerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerAddressNotFound'
'500':
$ref: '#/components/responses/internalServerError'
delete:
tags:
- Customer Self
summary: Delete Address - Customer Context
description: >-
Using this endpoint, a customer can delete their own address through the
storefront UI based on `addressId`.
operationId: deleteCustomersAddressSelf
responses:
'200':
$ref: '#/components/responses/deleteCustomerAddressResponse'
'400':
$ref: '#/components/responses/badRequest'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/customerAddressNotFound'
'500':
$ref: '#/components/responses/internalServerError'
components:
securitySchemes:
bearerAuth:
description: The access token.
type: http
scheme: bearer
bearerFormat: JWT
parameters:
xFabricTenantId:
name: x-fabric-tenant-id
in: header
description: >-
A header used by fabric to identify the tenant making the request. You
must include tenant id in the authentication header for an API request
to access any of fabric’s endpoints. You can retrieve the tenant id ,
which is also called account id, from
[Copilot
# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-customers-openapi.yml