Metadata

Updateable Smartbills objects—including Receipts, Customers, Products, and Merchants—have a metadata parameter. You can use this parameter to attach key-value data to these Smartbills objects.

Overview

Metadata allows you to store additional, structured information on an object. This is useful for:

Linking Smartbills objects to your internal systems
Storing custom business logic data
Adding context that’s specific to your application
Tracking additional information not covered by standard fields

Smartbills doesn’t use metadata for any internal purposes—for example, we don’t use it to authorize or decline operations, and it won’t be seen by your users unless you choose to show it to them.

Don’t store any sensitive information (like passwords, API keys, or personal identification numbers) as metadata.

Limitations

Maximum keys: 50 keys per object
Key name length: Up to 40 characters
Value length: Up to 500 characters
Format: Key-value pairs (both must be strings)

Supported Objects

Metadata can be attached to the following object types:

Receipts
Customers
Products
Merchants
Locations
Employees
Expenses
Expense Reports

Adding Metadata

You can add metadata when creating or updating an object:

// Creating a receipt with metadata
const response = await fetch('https://api.smartbills.io/v1/receipts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchantId: 123,
    total: { amount: 49.99, currency: 'USD' },
    metadata: {
      order_id: 'ORD-12345',
      customer_segment: 'premium',
      campaign_id: 'SUMMER2024',
      internal_notes: 'VIP customer'
    }
  })
});

import requests

# Creating a customer with metadata
response = requests.post(
    'https://api.smartbills.io/v1/customers',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'email': '[email protected]',
        'name': 'John Doe',
        'metadata': {
            'crm_id': 'CRM-98765',
            'account_tier': 'gold',
            'signup_source': 'mobile_app',
            'referral_code': 'REF123'
        }
    }
)

using System.Net.Http;
using System.Text.Json;

// Creating an expense with metadata
var expense = new
{
    amount = 125.50,
    currency = "USD",
    merchant = "Office Supplies Inc",
    metadata = new Dictionary<string, string>
    {
        { "project_id", "PROJ-456" },
        { "department", "Marketing" },
        { "cost_center", "CC-789" },
        { "approval_required", "true" }
    }
};

var content = new StringContent(
    JsonSerializer.Serialize(expense),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://api.smartbills.io/v1/expenses",
    content
);

Updating Metadata

You can update metadata on existing objects:

// Update metadata on existing receipt
const response = await fetch('https://api.smartbills.io/v1/receipts/12345', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    metadata: {
      order_id: 'ORD-12345',
      status: 'processed',
      processed_date: '2024-01-15'
    }
  })
});

# Update metadata on existing customer
response = requests.patch(
    'https://api.smartbills.io/v1/customers/67890',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'metadata': {
            'crm_id': 'CRM-98765',
            'last_purchase': '2024-01-15',
            'lifetime_value': '5000'
        }
    }
)

// Update metadata on existing expense
var update = new
{
    metadata = new Dictionary<string, string>
    {
        { "project_id", "PROJ-456" },
        { "approved_by", "[email protected]" },
        { "approval_date", "2024-01-15" }
    }
};

var content = new StringContent(
    JsonSerializer.Serialize(update),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PatchAsync(
    "https://api.smartbills.io/v1/expenses/12345",
    content
);

When updating metadata, the entire metadata object is replaced. Include all keys you want to keep, not just the ones you’re changing.

Retrieving Metadata

Metadata is included in the object response:

{
  "id": 12345,
  "merchantId": 123,
  "total": {
    "amount": 49.99,
    "currency": "USD"
  },
  "metadata": {
    "order_id": "ORD-12345",
    "customer_segment": "premium",
    "campaign_id": "SUMMER2024",
    "internal_notes": "VIP customer"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Deleting Metadata

To remove specific metadata keys, set them to null:

// Remove specific metadata keys
const response = await fetch('https://api.smartbills.io/v1/receipts/12345', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    metadata: {
      order_id: 'ORD-12345',
      campaign_id: null,  // This key will be removed
      internal_notes: null  // This key will be removed
    }
  })
});

# Remove specific metadata keys
response = requests.patch(
    'https://api.smartbills.io/v1/receipts/12345',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'metadata': {
            'order_id': 'ORD-12345',
            'campaign_id': None,  # This key will be removed
            'internal_notes': None  # This key will be removed
        }
    }
)

To remove all metadata, set the metadata field to an empty object:

{
  "metadata": {}
}

Sample Use Cases

Link Internal IDs

Attach your system’s unique IDs to Smartbills objects to simplify lookups.

{
  "metadata": {
    "internal_order_id": "ORD-12345",
    "erp_transaction_id": "TXN-98765",
    "accounting_reference": "ACC-456"
  }
}

Track Business Context

Store business-specific information for reporting and analytics.

{
  "metadata": {
    "department": "Marketing",
    "cost_center": "CC-789",
    "project_code": "PROJ-2024-Q1",
    "budget_category": "Advertising"
  }
}

Customer Segmentation

Annotate customers with segmentation data.

{
  "metadata": {
    "customer_tier": "gold",
    "acquisition_channel": "mobile_app",
    "referral_source": "friend",
    "lifetime_value_segment": "high"
  }
}

Workflow Tracking

Track approval workflows and processing status.

{
  "metadata": {
    "approval_status": "pending",
    "approver_id": "USER-123",
    "submitted_date": "2024-01-15",
    "workflow_step": "manager_review"
  }
}

Campaign Tracking

Associate receipts or transactions with marketing campaigns.

{
  "metadata": {
    "campaign_id": "SUMMER2024",
    "promo_code": "SAVE20",
    "utm_source": "email",
    "utm_campaign": "newsletter_jan"
  }
}

Filtering by Metadata

You can filter list requests by metadata values:

GET /v1/receipts?metadata[order_id]=ORD-12345
GET /v1/customers?metadata[customer_tier]=gold
GET /v1/expenses?metadata[department]=Marketing

// Filter receipts by metadata
const params = new URLSearchParams({
  'metadata[campaign_id]': 'SUMMER2024',
  'metadata[customer_segment]': 'premium'
});

const response = await fetch(
  `https://api.smartbills.io/v1/receipts?${params}`,
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

# Filter customers by metadata
params = {
    'metadata[customer_tier]': 'gold',
    'metadata[signup_source]': 'mobile_app'
}

response = requests.get(
    'https://api.smartbills.io/v1/customers',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params=params
)

Best Practices

Use Consistent Naming

Use a consistent naming convention for metadata keys across your application.

// Good: Consistent snake_case
{
  "order_id": "ORD-123",
  "customer_tier": "gold",
  "cost_center": "CC-789"
}

// Avoid: Mixed conventions
{
  "orderId": "ORD-123",
  "customer_tier": "gold",
  "CostCenter": "CC-789"
}

Document Your Metadata Schema

Maintain documentation of which metadata keys you use and their purposes.

Validate Metadata Values

Validate metadata values in your application before sending to the API.

function validateMetadata(metadata) {
  for (const [key, value] of Object.entries(metadata)) {
    if (key.length > 40) {
      throw new Error(`Key "${key}" exceeds 40 characters`);
    }
    if (value && value.length > 500) {
      throw new Error(`Value for "${key}" exceeds 500 characters`);
    }
  }
  return true;
}

Don't Store Sensitive Data

Never store sensitive information in metadata:

Passwords or API keys
Credit card numbers
Social security numbers
Personal health information
Any PII that requires encryption

Use Metadata for Filtering

Design your metadata schema to support efficient filtering and querying.

Error Handling

Common metadata-related errors:

Error Code	Description	Solution
`METADATA_KEY_TOO_LONG`	Key exceeds 40 characters	Use shorter key names
`METADATA_VALUE_TOO_LONG`	Value exceeds 500 characters	Truncate or store elsewhere
`METADATA_TOO_MANY_KEYS`	More than 50 keys	Remove unnecessary keys
`INVALID_METADATA_FORMAT`	Invalid JSON format	Ensure proper JSON encoding

Example: Complete Integration

Here’s a complete example showing how to use metadata in a real-world scenario:

class ReceiptManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.smartbills.io/v1';
  }
  
  async createReceiptWithMetadata(receiptData, internalData) {
    // Validate metadata
    const metadata = {
      order_id: internalData.orderId,
      customer_segment: internalData.customerTier,
      campaign_id: internalData.campaignId,
      store_location: internalData.storeCode,
      sales_rep: internalData.salesRepId
    };
    
    // Create receipt
    const response = await fetch(`${this.baseUrl}/receipts`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        ...receiptData,
        metadata
      })
    });
    
    return response.json();
  }
  
  async findReceiptByOrderId(orderId) {
    const params = new URLSearchParams({
      'metadata[order_id]': orderId
    });
    
    const response = await fetch(
      `${this.baseUrl}/receipts?${params}`,
      {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      }
    );
    
    const data = await response.json();
    return data.data[0]; // Return first match
  }
}

API Reference

Complete API documentation

Best Practices

Learn API best practices

Getting Started

Core Concepts

Expenses

Business Expenses

Expense Reports

Mileage

Approvals

Bills & Accounts Payable

Vendors

Vault

Team & Administration

Settings

Mobile App

Metadata

Metadata

Overview

Limitations

Supported Objects

Adding Metadata

Updating Metadata

Retrieving Metadata

Deleting Metadata

Sample Use Cases

Filtering by Metadata

Best Practices

Error Handling

Example: Complete Integration

API Reference

Best Practices

​Metadata

​Overview

​Limitations

​Supported Objects

​Adding Metadata

​Updating Metadata

​Retrieving Metadata

​Deleting Metadata

​Sample Use Cases

​Filtering by Metadata

​Best Practices

​Error Handling

​Example: Complete Integration

​Related Resources

API Reference

Best Practices

Metadata

Overview

Limitations

Supported Objects

Adding Metadata

Updating Metadata

Retrieving Metadata

Deleting Metadata

Sample Use Cases

Filtering by Metadata

Best Practices

Error Handling

Example: Complete Integration

Related Resources