Budgets API Overview

The Budgets API allows you to create, manage, and track budgets programmatically. This is the core functionality of Billoget, enabling you to integrate budget management into your applications.

🎯 What You Can Do

With the Budgets API, you can:

Create budgets with multiple items and detailed information
List and filter budgets by status, customer, date range, etc.
Update budget details including items, status, and metadata
Track budget lifecycle from creation to approval/rejection
Generate budget reports and analytics
Manage budget approvals and workflows

📊 Budget Object

Budget Structure

{
  "id": "budget_1234567890abcdef",
  "customerId": "customer_456789abcdef",
  "status": "PENDING",
  "total": 2500.0,
  "subtotal": 2100.0,
  "tax": 400.0,
  "discount": 0.0,
  "currency": "USD",
  "validUntil": "2024-02-15T23:59:59Z",
  "notes": "Q1 Marketing Campaign Budget",
  "items": [
    {
      "id": "item_123",
      "productId": "product_789",
      "description": "Premium Marketing Package",
      "quantity": 2,
      "unitPrice": 1000.0,
      "total": 2000.0,
      "tax": 0.0,
      "discount": 0.0
    },
    {
      "id": "item_124",
      "productId": "product_790",
      "description": "Additional Services",
      "quantity": 1,
      "unitPrice": 100.0,
      "total": 100.0,
      "tax": 0.0,
      "discount": 0.0
    }
  ],
  "customer": {
    "id": "customer_456789abcdef",
    "name": "Acme Corporation",
    "email": "contact@acme.com"
  },
  "metadata": {
    "source": "api",
    "campaign": "Q1_2024",
    "department": "marketing"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "approvedAt": null,
  "approvedBy": null
}

Field Descriptions

Field	Type	Description
`id`	string	Unique budget identifier
`customerId`	string	Associated customer ID
`status`	string	Budget status (PENDING, APPROVED, REJECTED, EXPIRED)
`total`	number	Total budget amount including tax
`subtotal`	number	Subtotal before tax and discounts
`tax`	number	Total tax amount
`discount`	number	Total discount amount
`currency`	string	Currency code (ISO 4217)
`validUntil`	string	Budget expiration date (ISO 8601)
`notes`	string	Additional notes or description
`items`	array	Array of budget items
`customer`	object	Customer information (read-only)
`metadata`	object	Custom metadata fields
`createdAt`	string	Creation timestamp
`updatedAt`	string	Last update timestamp
`approvedAt`	string	Approval timestamp (if approved)
`approvedBy`	string	User who approved the budget

📋 Budget Statuses

Status	Description
`PENDING`	Budget is waiting for review/approval
`APPROVED`	Budget has been approved
`REJECTED`	Budget has been rejected
`EXPIRED`	Budget has passed its valid until date
`DRAFT`	Budget is still being prepared

🔄 Available Operations

List Budgets

GET /api/public/budgets

Retrieve a paginated list of budgets with filtering options.

Get Budget

GET /api/public/budgets/{id}

Retrieve a specific budget by its ID.

Create Budget

POST /api/public/budgets

Create a new budget with items and customer information.

Update Budget

PUT /api/public/budgets/{id}

Update an existing budget's details, items, or status.

Delete Budget

DELETE /api/public/budgets/{id}

Delete a budget (soft delete - can be recovered).

🎯 Quick Examples

Create a Simple Budget

curl -X POST "https://api.billoget.com/v1/api/public/budgets" \
  -H "Authorization: Bearer bk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_456789abcdef",
    "items": [
      {
        "productId": "product_789",
        "quantity": 2,
        "unitPrice": 500.00,
        "description": "Consulting Services"
      }
    ],
    "notes": "Initial consultation budget",
    "validUntil": "2024-03-31T23:59:59Z"
  }'

List Recent Budgets

curl -X GET "https://api.billoget.com/v1/api/public/budgets?limit=10&sort=createdAt&order=desc" \
  -H "Authorization: Bearer bk_live_1234567890abcdef"

Update Budget Status

curl -X PUT "https://api.billoget.com/v1/api/public/budgets/budget_123" \
  -H "Authorization: Bearer bk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "APPROVED",
    "notes": "Approved by manager"
  }'

🔍 Filtering and Search

Available Filters

Parameter	Type	Description	Example
`status`	string	Filter by status	`?status=PENDING`
`customerId`	string	Filter by customer	`?customerId=customer_123`
`minTotal`	number	Minimum total amount	`?minTotal=1000`
`maxTotal`	number	Maximum total amount	`?maxTotal=5000`
`createdAfter`	string	Created after date	`?createdAfter=2024-01-01`
`createdBefore`	string	Created before date	`?createdBefore=2024-12-31`
`search`	string	Search in notes/description	`?search=marketing`

Example Filtered Request

curl -X GET "https://api.billoget.com/v1/api/public/budgets?status=PENDING&minTotal=1000&search=marketing" \
  -H "Authorization: Bearer bk_live_1234567890abcdef"

🚨 Common Errors

Validation Errors

{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "errors": [
      {
        "field": "customerId",
        "code": "REQUIRED",
        "message": "Customer ID is required"
      },
      {
        "field": "items",
        "code": "MIN_LENGTH",
        "message": "At least one item is required"
      }
    ]
  }
}

Not Found Error

{
  "error": "resource_not_found",
  "message": "Budget with ID 'budget_123' not found",
  "details": {
    "resource": "budget",
    "id": "budget_123"
  }
}

🎯 Best Practices

1. Always Include Customer Information

Ensure the customer exists before creating a budget:

// Check customer exists first
const customer = await api.getCustomer(customerId);
if (!customer) {
  throw new Error('Customer not found');
}

// Then create budget
const budget = await api.createBudget({
  customerId: customer.id,
  items: [...],
  // ...
});

2. Handle Item Calculations

Let the API calculate totals automatically, or provide your own:

const budgetData = {
  customerId: "customer_123",
  items: [
    {
      productId: "product_456",
      quantity: 2,
      unitPrice: 100.0,
      // total will be calculated automatically (200.00)
    },
  ],
  // tax and total will be calculated based on items
};

3. Set Appropriate Expiration Dates

Always set a reasonable validUntil date:

const budget = {
  // ... other fields
  validUntil: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(), // 30 days from now
};

4. Use Metadata for Integration

Store integration-specific data in metadata:

const budget = {
  // ... other fields
  metadata: {
    source: "shopify",
    orderId: "order_123",
    campaignId: "campaign_456",
    externalRef: "ext_789",
  },
};

📚 Next Steps

Budget Endpoints - Complete API reference for all budget operations

API Overview - General API information
Webhooks - Get notified of budget changes
Postman Collection - Test budget endpoints

Ready to start working with budgets? Let's explore the budget endpoints! 📋

🎯 What You Can Do​

📊 Budget Object​

Budget Structure​

Field Descriptions​

📋 Budget Statuses​

🔄 Available Operations​

List Budgets​

Get Budget​

Create Budget​

Update Budget​

Delete Budget​

🎯 Quick Examples​

Create a Simple Budget​

List Recent Budgets​

Update Budget Status​

🔍 Filtering and Search​

Available Filters​

Example Filtered Request​

🚨 Common Errors​

Validation Errors​

Not Found Error​

🎯 Best Practices​

1. Always Include Customer Information​

2. Handle Item Calculations​

3. Set Appropriate Expiration Dates​

4. Use Metadata for Integration​

📚 Next Steps​

🔗 Related Resources​