Retrieve Customer Tag

The Retrieve Customer Tag feature in Payiano is all about focusing on a specific customer group. Imagine you have a tag for 'frequent buyers' and you want to see who's in this group. This feature lets you do just that. It provides detailed information about the specific tag, like which customers are included under it. This is really useful for when you need to understand or communicate with a particular customer segment, helping you make more informed decisions and offer more personalized services.

GET/customer_tags/{id}
Sandbox: https://api.payiano.dev/v1/customer_tags/{id}
Live: https://api.payiano.com/v1/customer_tags/{id}
Security
  • Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
  • Your access token should be associated to this permission customer_tags_view
Request
Request body schema:
application/json
Path parameters:
id
required
Type: ulid
Length: 26

The unique ID assigned to each customer tag 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 tag. This ULID is automatically created by our system and is used to uniquely identify and track each customer tag in our database.

Query parameters:
identify_by
Type: enum|null
Possible values:
[
"id", "reference_id" ]

This attribute specifies which identifier is being used to interact with a resource in the Payiano API. It helps the system understand how to identify resource when processing API requests. By default, the identify_by attribute is set to id, so you only need to specify it if you're using a different identifier.

includes
Type: array_of_enums|null
Possible values:
[
"customer_tag.metadata" ]

A list of additional customer tag relations to return, if available. Feel free to send the relations you would like to return with every item. See Including Resources to better understand how this is working.

Response
200
Response schema:
application/json
Response body:
customer_tag
Type: object

The customer tag model details.

id
Type: ulid
Length: 26

The unique ID assigned to each customer tag 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 tag. This ULID is automatically created by our system and is used to uniquely identify and track each customer tag in our database.

name
Type: string
Min: 1
Max: 100

This attribute serves as the identifier or label for the group. It's a concise and clear title that represents the essence of the group. For instance, a name could be 'Frequent Buyers' or 'Newsletter Subscribers'. This attribute should be chosen to reflect the common characteristic or purpose that links the customers in this tag, making it easy to identify and reference the group at a glance. Please notice that duplicate values are not allowed and it's allowed to use alpha dash only [A-Za-z0-9-_ ].

is_active
Type: boolean
Default: true

This value indicates whether the customer tag is active or not. This flag can be used to control the customer tag's availability in runtime environments or listings without deleting or removing the customer tag from records. A true value means the customer tag is active and functioning, while a false value implies that the customer tag is deactivated or not in use.

reference_id
Type: string|null
Max: 50

It's a unique identifier assigned to each customer tag. It's primary role is to distinguish one customer tag from another, ensuring that each customer tag can be individually tracked and managed without any confusion. Please notice that duplicate values are not allowed and it's allowed to use alpha dash only [A-Za-z0-9-_]. The reference_id value is used to Identify Resource when you consume any customer tag endpoint with sending identify_by query parameter with value reference_id.

description
Type: string|null
Max: 10000

This attribute provides more detailed information about the customer tag. It's where you can explain the purpose or characteristics of the group in more depth. For example, for a tag named 'Frequent Buyers', the description might elaborate on criteria like “Customers who make purchases more than twice a month.” This attribute is particularly useful for understanding the context and nuances of the customer group, guiding how you interact with and cater to this segment.

metadata
Type: object|null

The customer tag metadata model details. Metadata serves as a tool for keeping extra, organized details about a resource. For example, you can use it to store a user's preferences like prefered color, notes or any other data that aids in personalizing services, improving customer relations, or optimizing internal workflows. This information isn't utilized by Payiano – meaning it's not involved in authorizing or declining transactions and remains invisible to your users. Its value is entirely private for your internal use, and we ensure it remains confidential, not shared with any external parties.

info
Type: array_of_objects
Max: 50

This array consists of objects, each containing a key and a value. These pairs of key-value are structured in a way that's more suitable for programmatic access. You can add up to 50 objects.

key
Type: string
Min: 1
Max: 50

It's a unique identifier to avoid confusion or data overlap. The keys serve as identifiers for the corresponding values, making it easier to retrieve specific pieces of information as needed.

value
Type: string
Min: 1
Max: 255

The value is the actual data associated with that key. It could be a simple string, a number, a URL, or any other data format that conveys the necessary information.

list
Type: array_of_strings
Max: 50

The list attribute is particularly useful for scenarios where the data needs to be presented in a straightforward, unstructured format. It's ideal for quick overviews, simple data logging, or when the information does not require the more complex organization that nested JSON objects provide. Please notice that duplicate values are not allowed, you can add up to 50 item and the max list item length is 255 characters.

is_deleted
Type: boolean
Default: false

This value indicates whether the customer tag is deleted or not. This flag can be used to control the customer tag's availability in runtime without actual deleting or removing the customer tag from records. A true value means the customer tag is deleted, while a false value implies that the customer tag is not deleted and functioning.

created_at
Type: datetime

The created datetime of the customer tag. 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
Type: datetime

The updated datetime of the customer tag. 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
Type: datetime|null

The deleted datetime of the customer tag. 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.

Response sample:
1
{
2
"customer_tag": {
3 "id": "01hqjp31wcww3jhnagehc16r04", 4 "name": "Frequent Buyers", 5 "is_active": true, 6 "reference_id": "7193edd2-7574-3b76-9103-e0e37580129b", 7 "description": "Customers who make purchases more than twice a month.", 8
"metadata": {
9
"info": [
10
{
11 "key": "Company name", 12 "value": "Pyngy" 13 } 14 ], 15
"list": [
16 "Cairo, Nasr City, 7th District, Building 12 floor 5" 17 ] 18 }, 19 "is_deleted": false, 20 "created_at": "1722572118554", 21 "updated_at": "1722572118554", 22 "deleted_at": null 23 } 24}