openapi: 3.0.1
info:
title: Cart Actions Endpoints Customer Address 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 Address
description: These endpoints provide the features for store admins to create and manage customers' addresses.
paths:
/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'
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
deleteCustomerAddressResponse:
description: Delete customer address response
headers:
x-fabric-request-id:
$ref: '#/components/responses/forbidden/headers/x-fabric-request-id'
content:
application/json:
schema:
$ref: '#/components/schemas/message'
examples:
customerAddressDeletionSuccess:
value:
type: CUSTOMER_ADDRESS_DELETED_SUCCESSFULLY
message: Customer address deleted successfully
customerAddressDeletedAlready:
value:
type: CUSTOMER_ADDRESS_DELETED_SUCCESSFULLY
message: Customer address already deleted
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
customerAddressNotFound:
description: The specified 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'
examples:
CustomerNotFound:
value:
type: CUSTOMER_NOT_FOUND
message: Data with the given identifier isn't found.
CustomerAddressNotFound:
value:
type: CUSTOMER_ADDRESS_NOT_FOUND
message: Data with the given identifier isn't found.
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.
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
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](/v3/platform/settings/account-details/getting-the-account-id). This header is required.
schema:
type: string
example: 517fa9dfd42d8b00g1o3k312
customerIdPathParam:
in: path
name: customerId
description: A 24-character system-generated ID of the customer. This is returned in the response of the `POST /customers` endpoint.
required: true
style: simple
schema:
type: string
example: 61a558b1b155125f02be7fb1
addressIdPathParam:
in: path
name: addressId
description: A 24-character system-generated ID of the customer's address.
required: true
style: simple
schema:
type: string
example: 61a558b1b155125f02be7fb2
xFabricRequestId:
name: x-fabric-request-id
in: header
description: A UUID of the request.
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
required: false
schemas:
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
updateCommonAddressRequest:
type: object
description: The address details.
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, for additional information.
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
country:
description: The country code, which can be a full name, an ISO 3166-1 alpha-2, or alpha-3 code.
type: string
example: US
latitude:
description: The geographical `latitude` used with `longitude` to locate an 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 an address. The coordinates are provided in decimal degrees format, with negative values indicating locations to the west.
type: number
format: double
example: -122.3493
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
searchAddressLine:
type: object
description: The criteria to search by the first, second, or third line of the customer's address.
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 first, second, or third line of the customer's address.
example: 123 Main St.
required:
- op
- value
listCustomerAddressResponse:
description: The list of customer addresses for the customerId.
type: object
properties:
query:
$ref: '#/components/schemas/Query'
data:
description: addresses of the sent customer
type: array
items:
$ref: '#/components/schemas/customerAddressResponse'
searchIsDefault:
type: boolean
description: A flag indicating whether the search results should include only default addresses. Set to 'true' to include only default addresses and 'false' to exclude default addresses.
enum:
- false
- true
example: true
searchCountry:
type: object
description: The criteria to search for the customer's address based on the `country` given in the address.
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 country code, which can be a full name, ISO 3166-1 alpha-2, or an alpha-3 code.
example: US
required:
- op
- value
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'
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
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
updateCustomerAddressRequest:
type: object
properties:
address:
$ref: '#/components/schemas/updateCommonAddressRequest'
isDefault:
description: A flag indicating whether the address is the default one. `true` indicates the address is the default address and `false` indicates otherwise.
type: boolean
example: false
additionalAttributes:
description: A placeholder for additional info, in key-value pairs.
type: object
example:
landmark: Beach
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
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
customerAddressSearchRequest:
type: object
description: The criteria to search for customer's addresses.
required:
- match
properties:
sort:
type: string
description: The criteria to sort results, where `-` indicates a descending order and `+` indicates an ascending order. You can sort the following fields - `createdAt`, `updatedAt`, `type`, and `country`.
example: -createdAt
match:
description: match
allOf:
- $ref: '#/components/schemas/customerAddressMatch'
offset:
type: number
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.
default: 0
example: 0
limit:
type: number
description: The maximum number of records in a single page.
example: 10
default: 20
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
searchType:
type: object
description: The criteria to search based on the type of address.
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 type of address.
enum:
- BILLING
- SHIPPING
example: BILLING
required:
- op
- value
searchLongitude:
type: object
description: The criteria to search for customer's address based on longitude or a range of longitude given in the address.
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: number
description: The longitude value in decimal degrees format; negative is degrees West.
format: double
example: -77.0364
startLongitude:
type: number
description: The starting value of the longitude range. This is used with the `endLongitude` property and formatted to decimal degrees; negative is degrees West.
format: double
example: -77.0364
endLongitude:
type: number
format: double
description: The ending value of the longitude range. This is used with the `startLongitude` property and formatted to decimal degrees; negative is degrees West.
example: -77.0364
example:
op: LTE
value: -77.0364
required:
- op
customerAddressMatch:
type: object
description: The criteria to search for customer's address.
properties:
id:
$ref: '#/components/schemas/searchId'
type:
$ref: '#/components/schemas/searchType'
addressLine1:
$ref: '#/c
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-customer-address-api-openapi.yml