The list customer addresses feature in Payiano acts
as an online address book tailored for businesses. It consolidates all
customer addresses into one centralized location, offering exceptional
convenience. This feature is transformative for accurately sending products,
crafting targeted promotions based on customer locations, and ensuring each
customer feels appreciated with personalized deals and updates relevant to
their area.
Easy access to this organized list allows businesses to deliver products
efficiently, foster a closer relationship with their customers by tailoring
their offerings, and increase customer satisfaction by showing a deep
understanding of their preferences and requirements. It's all about making
business operations smoother and keeping customers engaged and content by
making sure they're getting exactly what they need, when they need it, where
they live.
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission client.customer_addresses.view
Request
Request body schema:
application/json
Path parameters:
customer_id
required
customer_id
required
Type: ulid
Length: 26
The unique ID assigned to each customer which is generated
by our system using the ULID format. Each ID is
precisely 26 characters long, ensuring a unique and consistent
identifier for every customer. This ULID is
automatically created by our system and is used to uniquely identify
and track each customer in our database.
Query parameters:
page
page
Type: integer|null
Default: 1
The page number to be retrieved, for the list of customer address.
So, a combination of page=1 and per_page=25 returns the
first 25 customer address items. A combination of page=2 and
per_page=25 returns the next 25 customer address items.
per_page
per_page
Type: integer|null
Default: 25
Possible values: [1 ... 200]
The maximum number of customer address items to return in the response.
q
q
Type: string|null
Min: 3
This parameter enables free-text search across key customer address fields
(including but not limited to type, line_one and line_two), requiring a minimum of
3 characters per search term. It performs case-insensitive partial
matching, and returns relevance-ranked results while automatically handling
special characters. This provides a simple yet powerful way to quickly find
relevant customer address items. It could accept an array_of_strings as well.
sort
sort
Type: array_of_objects|null
Control the ordering of results with sophisticated multi-column sorting.
Specify an array of objects, each containing a field and direction.
Maximum 5 sort fields per request to maintain
optimal performance.
This attribute specifies the field used for sorting. It can be a direct
attribute of the resource or a related field referenced using dot notation.
direction
required
direction
required
Type: enum
Possible values:
JSON
["asc","desc"]
This attribute specifies the sorting direction. It can be either asc
for ascending order or desc for descending order. Please note that
the value is case-sensitive.
includes
includes
Type: array_of_enums|null
Possible values:
JSON
["customer_address.country"]
A list of additional customer address related objects to eager-load
and return with the response. Pass only the relations you need to
keep response payloads lean.
See Including Resources
for the full list of supported include values and usage details.
filters
filters
Type: object|null
Apply complex filtering conditions using nested logical groups and comparison
operators. Supports advanced querying with and/or logic, multiple
operators, and hierarchical conditions.
The filtering system supports unlimited nesting depth , allowing you to build sophisticated query logic. Each group can contain a mix of conditions and other groups. See Filtering Reference for complete documentation, operator list, and examples.
node
required
node
required
Type: enum
Possible values:
JSON
["group"]
Used exclusively as the root filter node.
Specifies the type of the root filter node. At the root level,
only a logical group node is supported. A group node acts as a container that
combines one or more filter conditions or nested groups using AND/OR logic.
Nested group and condition nodes may appear within this root group to build
complex filtering structures.
logic
required
logic
required
Type: enum
Possible values:
JSON
["and","or"]
This parameter is used exclusively on group nodes.
Defines how filters within a filter group are logically combined. This
parameter is used exclusively on group nodes and determines how the group
evaluates its child filters or nested groups:
• and — all contained conditions must match
• or — at least one contained condition must match
Logical groups can be nested to construct complex filtering expressions with
mixed AND/OR logic across multiple levels.
filters
required
filters
required
Type: array_of_objects
This parameter is used exclusively on group nodes.
Contains the filter nodes (conditions or groups) within this logical group.
Groups can be nested to create complex hierarchical filtering logic.
node
node
Type: enum
Possible values:
JSON
["group","condition"]
Specifies the type of filter node. A filter node can be either a logical
group or a condition:
• group — a logical grouping of multiple filters combined with AND/OR logic
• condition — a single filter condition specifying a field, operator, and value
Filter nodes can be nested to create complex filtering structures.
logic
logic
Type: enum
Possible values:
JSON
["and","or"]
This parameter is used exclusively on group nodes.
Defines how filters within a filter group are logically combined. This
parameter is used exclusively on group nodes and determines how the group
evaluates its child filters or nested groups:
• and — all contained conditions must match
• or — at least one contained condition must match
Logical groups can be nested to construct complex filtering expressions with
mixed AND/OR logic across multiple levels.
filters
filters
Type: array_of_objects
This parameter is used exclusively on group nodes.
Contains the filter nodes (conditions or groups) within this logical group.
Groups can be nested to create complex hierarchical filtering logic.
This parameter is used exclusively on condition nodes.
It specifies the field evaluated by the filter condition. The selected
field determines which operators are available and the expected format
of the comparison value based on its data type.
This parameter is used exclusively on condition nodes.
It specifies the comparison operator applied to the selected field. The set of
supported operators depends on the field and its data type, and only operators
that are valid for the chosen field can be used. Available operators for each
field are provided in the response and presented in the filter selection.
Refer to the Filtering Reference for
the complete operator list, expected value formats, and usage examples.
value
value
Type: mixed
This parameter is used exclusively on condition nodes.
The value used by the selected operator to evaluate the field. The expected
structure and data type of this parameter depend on both the field type and
the operator:
• Scalar operators (eq, not_eq, gt, gte, lt, lte,
starts_with, ends_with, contains, and their negations) expect a
single value matching the field type (for example, string or number).
• List operators (in, not_in) expect an array of values compatible
with the field type.
• Range operators (between, not_between) expect an array of exactly
two values representing the inclusive lower and upper bounds.
• Null-check operators (is_null, is_not_null) do not accept a value
and must be used without this parameter.
Supplying a value that does not match the operator or field type will result
in a validation error in strict mode.
See the Filtering Reference for
supported operators, applicable field types, and examples.
Specifies the output format of the datatable response, supporting both
JSON and export file types for easy integration and reporting.
Refer to Response Types
for more details.
aggregations
aggregations
Type: object|null
Defines how to aggregate and group data when
response_type is set to json_aggregate. This parameter enables analytical
style responses suitable for dashboards and reports. Refer to
Aggregations for more details.
fields
required
fields
required
Type: array_of_objects
Defines the fields to be aggregated along with their respective metrics.
Maximum 5 aggregation fields per
request to maintain optimal performance.
This attribute specifies the name of the field to be aggregated.
metrics
required
metrics
required
Type: array_of_enums
Possible values:
JSON
["avg","count","sum"]
Defines the aggregation metrics to apply to the selected field.
Note that the avg and sum metrics are applicable
only to numeric fields.
group_by
required
group_by
required
Type: array_of_objects|null
Specifies the dimensions used to group aggregated
data results. Each object defines a field by which records will be
grouped before applying aggregation metrics. Maximum
5 aggregation group by
fields per request to maintain optimal performance.
Grouping enables developers to analyze data trends across categories, dates,
or other meaningful dimensions.
If no group_by fields are provided, the system performs a global aggregation across the entire dataset. In such cases, the response includes a single summary group, typically referencing the latest created_at value.
Specifies the field name used for grouping results within the aggregation.
This determines how records are organized and segmented when computing metrics.
When grouping by a datetime or timestamp field such as created_at , the system automatically groups by the date portion only , ignoring the time component. This enables daily-based aggregations instead of precise timestamp level grouping.
By default, grouping operations use the server's timezone ( UTC ). You can override this behavior by specifying the X-Preferred-Response-Timezone header in your request. Learn more about timezone handling in our Datetime & Timezone Reference.
Response
200
Response schema:
application/json
Response body:
total_pages
total_pages
Type: integer
The total number of pages that are available for the customer address
search criteria.
current_page
current_page
Type: integer
The current pagination page.
per_page
per_page
Type: integer
The amount of customer address items returned per page.
total_items
total_items
Type: integer
The total number of customer address that match the search criteria.
items
items
Type: array_of_objects
The list of customer address that match the search criteria.
id
id
Type: ulid
Length: 26
The unique ID assigned to each customer address which is generated
by our system using the ULID format. Each ID is
precisely 26 characters long, ensuring a unique and consistent
identifier for every customer address. This ULID is
automatically created by our system and is used to uniquely identify
and track each customer address in our database.
country_code
country_code
Type: string
Specify the unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country where customer is located. This code is part of the standard
international country codes set by the ISO .
type
type
Type: enum
Possible values:
JSON
["billing_address","shipping_address"]
This attribute is used to differentiates between types of customer addresses,
such as billing or shipping address.
is_default
is_default
Type: boolean
Default: false
This attribute specifies if the address is the default one selected
for the customer for billing or shipping purposes. It comes into
play when the user is directed to the checkout page or when an
order is being delivered to them.
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each customer address. It's
primary role is to distinguish one customer address from another, ensuring
that each customer address can be individually tracked and managed without
any confusion.
Please note that duplicate values are not allowed. Only alpha-numeric
characters, dashes, and underscores are allowed: [A-Za-z0-9-_].
The reference_id
value is used to Identify Resource
when you consume any customer address endpoint with sending identify_by
query parameter with value reference_id.
line_one
line_one
Type: string|null
Min: 2
Max: 255
The primary address line, typically containing the building or house number and
street name. This field is required and must precisely identify the street-level
location for deliveries, correspondence, and geographic lookups.
line_two
line_two
Type: string|null
Min: 2
Max: 255
An optional secondary address line used for additional information like apartment,
suite, or building numbers that help refine the location for delivery services.
city
city
Type: string|null
Min: 2
Max: 50
This attribute specifies the city in which the address is located. It's essential
for routing mail and deliveries within the correct geographical area.
state
state
Type: string|null
Min: 2
Max: 50
The state or region attribute further narrows down the location, especially in
countries with large geographical areas divided into states, provinces, or regions.
zip_code
zip_code
Type: string|null
Min: 2
Max: 30
Also known as postal code in some regions, this numeric or alphanumeric code is
critical for sorting mail and determining delivery routes with precision.
phone_number
phone_number
Type: string|null
Max: 30
A primary contact number that can be a mobile or cellular number, providing a
direct line to the individual or entity associated with the address.
landline_number
landline_number
Type: string|null
Max: 30
An alternative to the mobile number, this is a fixed-line telephone number
associated with the location, useful for contact purposes where mobile signals
may be unreliable.
fax_number
fax_number
Type: string|null
Max: 30
An optional fax number associated with the address. Used to receive documents
transmitted over telephone lines in business or institutional contexts where fax
communication is still supported.
first_name
first_name
Type: string|null
Min: 2
Max: 50
The given name of the individual associated with the address, important for
personalizing communication and ensuring the correct recipient for mail or
services.
last_name
last_name
Type: string|null
Min: 2
Max: 50
The family or surname of the individual, completing the personal identification
and used in conjunction with the first name for full clarity on the recipient's
identity.
location
location
Type: object|null
This attribute is used to offer a precise, geographical identification of a
place, which is crucial for various applications like mapping, navigation,
and location-based services.
lat
lat
Type: decimal
Min: -90
Max: 90
The geographic latitude of the address, expressed in decimal degrees. Valid
values range from -90 (south pole) to 90 (north pole). Used together with
longitude to pinpoint the exact location on a map or coordinate system.
lng
lng
Type: decimal
Min: -180
Max: 180
The geographic longitude of the address, expressed in decimal degrees. Valid
values range from -180 (west) to 180 (east). Combined with latitude, provides
the precise GPS coordinates required for mapping and location-based services.
note
note
Type: string|null
Min: 2
Max: 255
This free-text field allows for additional information or special instructions
related to the address or delivery preferences to be included.
customer_id
customer_id
Type: ulid
This field is the key to associating each address
with the correct customer account, enhancing the personalization
and accuracy of the transaction process. It not only enhances
transaction precision but also contributes significantly to
effective customer relationship management and data analysis.
country
country
Type: object
A country object containing the official name, two-letter
ISO code, flag emoji, primary language, international dialing
code, and ISO currency code.
name
name
Type: string
The official name of the country in English or In Arabic if the
Accepted-Language header is set to ar. This is the commonly
recognized name that would be used in international contexts and
is essential for any application that references countries by name.
flag
flag
Type: string
A Unicode representation of the country's flag. Unlike an image URL,
Unicode flags are character codes that render as the country's flag
emoji across compatible digital platforms. This allows for easy
integration of flags into text-based content and interfaces without
needing external images.
lang
lang
Type: string|null
This attribute represents the primary language spoken in the country.
It's typically expressed in ISO 639-1 format,
a two-letter code identifying the language, making it easier for applications
to adapt content or interfaces according to the user's region.
code
code
Type: string
The unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country. This code is part of the standard
international country codes set by the ISO .
dial_code
dial_code
Type: string
The international dialing code for the country, such as +1 for
the United States, +44 for the United Kingdom or +20 for
Egypt. This code is crucial for making international telephone calls
and can be used in applications that require user phone number verification.
currency_code
currency_code
Type: string
This attribute describes the official currency used in the country,
typically denoted by its ISO currency code,
such as USD for the United States Dollar, EUR for the Euro or EGP for
Egyptian Pound.
is_deleted
is_deleted
Type: boolean
Default: false
Indicates whether the customer address has been soft-deleted. A true
value means the record is marked as deleted and excluded from standard
listings; a false value means it is active. Soft-deleted records
remain in the database and can be restored.
created_at
created_at
Type: datetime
The created datetime of the customer address.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format
specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
updated_at
updated_at
Type: datetime
The updated datetime of the customer address.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format
specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
deleted_at
deleted_at
Type: datetime|null
The deleted datetime of the customer address.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format
specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.