Custom Attributes

Store and query custom data on any API object

Every object has a predefined set of default attributes, which you can find in the object reference. Some objects also have non-default attributes which you can explicitly request to include in a response.

You also have the ability to add any custom attributes you want to any object.

Request Specific Attributes

Filter Attributes

If only certain attributes are needed, you can explicitly request which attributes you want returned.

filter.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
results = pl.Invoice.select(
    pl.attr.due_date, pl.attr.amount_due ).all()

Include Extra Attributes

If there's an additional attribute you want included in the response that is not a default attribute, you can specify that attribute and all default fields using the default attributes symbol, *.

include.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
results = pl.Invoice.select(
    pl.attr.processing, *pl.Invoice ).all()

Set Global Preferences

The software packages allow you to set global query string parameters by object resource using the default_params class attribute. You can use this to set the fields attribute to apply your preferences globally.

global.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
pl.Transaction.default_params = { 'fields':
	[ pl.attr.conv_fee, *pl.Transaction ] }

Set Custom Attributes

You can add any key/value custom attributes to any object by updating the attrs nested object.

Adding Custom Attributes

add.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
inv = pl.Invoice.get('inv_3axWdCgzecx9HR7PSOqP2')
 
inv.update(attrs={'custom': 'data'})

Complex Custom Attributes

You can store complex data structures in custom attributes:

complex.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Add multiple custom attributes with different data types
 
 
customer = pl.Account.get('cust_123')
customer.update(attrs={
    'preferences': {
        'theme': 'dark',
        'notifications': True,
        'language': 'en'
    },
    'tags': ['vip', 'enterprise'],
    'metadata': {
        'source': 'referral',
        'campaign': 'q4-2023',
        'score': 85
    }
})

Querying Custom Attributes

You can also query objects based on their custom attributes:

Query by Custom Attribute Values

query.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Find customers with specific custom attributes
 
 
vip_customers = pl.Account.filter_by(
    pl.attr.attrs.tags.contains('vip'),
).all()
 
# Find customers by preference
dark_theme_users = pl.Account.filter_by(
    pl.attr.attrs.preferences.theme == 'dark',
).all()

Use Cases for Custom Attributes

Business Logic

Store business-specific flags or status indicators
Add custom workflow states
Include integration-specific identifiers

business.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Business workflow example
 
 
transaction = pl.Transaction.create(
    type='payment',
    amount=99.99,
    sender={
        'account_id': 'acct_customer123'
    },
    attrs={
        'approval_status': 'pending',
        'sales_rep': 'john.doe',
        'priority': 'high',
        'custom_order_number': 'ORD-2023-001',
    }
)

Analytics and Tracking

Store UTM parameters or campaign data
Add custom tracking identifiers
Include A/B test variants

analytics.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Analytics example
 
 
customer = pl.Account.create(
    {
        'name': 'John Doe',
        'type': 'customer',
        'contact_details': {'email': '[email protected]'},
        'attrs': {
            'utm_source': 'google',
            'utm_campaign': 'summer-2023',
            'referral_code': 'FRIEND20',
            'ab_test_variant': 'checkout_v2',
        },
    }
)

Integration Data

Store third-party service IDs
Include external system references
Add synchronization timestamps

integration.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Integration example
 
invoice = pl.Invoice.create(
    due_date="2024-02-01",
    description="Monthly services",
    payer={"account_id": "acct_customer123"},
    items=[
        {
            "type": "line_item",
            "line_item": {
                "value": 199.99,
            },
            "description": "Service fee",
        }
    ],
    attrs={
        "quickbooks_id": "QB-INV-789",
        "salesforce_opportunity_id": "SF-OPP-456",
        "last_sync_at": "2023-12-01T10:30:00Z",
        "external_invoice_number": "EXT-2023-12001",
    },
)

Best Practices

Naming Conventions

Use descriptive, consistent naming for custom attributes
Consider using prefixes to organize attributes by purpose (e.g., crm_, analytics_, workflow_)
Avoid using reserved words or conflicting with existing attribute names

Data Structure

Use nested objects to organize related custom attributes
Keep the data structure as flat as possible for better queryability
Consider the data types supported by your target systems

Performance Considerations

Be mindful of the size of custom attribute data
Index frequently queried custom attributes if supported
Consider using separate objects for large amounts of custom data

Documentation

Document your custom attribute schema for team members
Include examples of expected data formats
Maintain consistency across your application

Functions Hierarchical Object Design