Budgets API Endpoints

The Budgets API provides complete CRUD operations for managing budgets in your Billoget integration. All endpoints require proper authentication and respect rate limiting.

Base URL

https://api.billoget.com/v1/api/public/budgets

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer bk_live_your_api_key_here

Endpoints Overview

Method	Endpoint	Description
POST	/budgets/public	Create a budget publicly (returns public URL)
GET	/budgets	List all budgets with pagination
GET	/budgets/{id}	Get a specific budget by ID
POST	/budgets	Create a new budget
PUT	/budgets/{id}	Update an existing budget
DELETE	/budgets/{id}	Delete a budget (soft delete)

---

Create Budget Publicly

Create a new budget and receive a public URL for viewing. This endpoint is designed for integrations where you want to create a budget and immediately share it with customers.

Request

POST /api/budgets/public

Request Body

{
  "currency": "USD",
  "issueDate": "2024-01-15T10:30:00Z",
  "expirationDate": "2024-02-15T23:59:59Z",
  "customerId": 123,
  "sellerId": 456,
  "businessId": 789,
  "minimumPaymentToConfirm": 100.0,
  "subtotal": 1000.0,
  "total": 1210.0,
  "iva": 210.0,
  "comments": "Budget for new project implementation",
  "items": [
    {
      "productId": 101,
      "quantity": 2,
      "unitPrice": 500.0
    },
    {
      "packageId": 201,
      "quantity": 1,
      "unitPrice": 210.0
    }
  ]
}

Request Body Schema

Field	Type	Required	Description
currency	string	Yes	Currency code (e.g., USD, EUR)
issueDate	string	Yes	Budget issue date (ISO 8601)
expirationDate	string	Yes	Budget expiration date (ISO 8601)
customerId	number	Yes	Customer ID
sellerId	number	Yes	Seller/User ID
businessId	number	No	Business ID (auto-assigned if omitted)
minimumPaymentToConfirm	number	Yes	Minimum payment required
subtotal	number	Yes	Subtotal amount
total	number	Yes	Total amount including taxes
iva	number	Yes	Tax amount
comments	string	No	Additional comments
items	array	Yes	Array of budget items
items[].productId	number	No	Product ID (for individual products)
items[].packageId	number	No	Package ID (for service packages)
items[].quantity	number	Yes	Item quantity
items[].unitPrice	number	Yes	Price per unit

Example Request

curl -X POST "https://api.billoget.com/v1/api/budgets/public" \
  -H "Authorization: Bearer bk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "issueDate": "2024-01-15T10:30:00Z",
    "expirationDate": "2024-02-15T23:59:59Z",
    "customerId": 123,
    "sellerId": 456,
    "minimumPaymentToConfirm": 100.0,
    "subtotal": 1000.0,
    "total": 1210.0,
    "iva": 210.0,
    "comments": "Budget for new project implementation",
    "items": [
      {
        "productId": 101,
        "quantity": 2,
        "unitPrice": 500.0
      }
    ]
  }'

Response

{
  "success": true,
  "message": "Budget created successfully",
  "publicUrl": "https://app.billoget.com/budget/123_abc789_xyz456",
  "budgetId": 124,
  "publicToken": "123_abc789_xyz456"
}

Response Schema

Field	Type	Description
success	boolean	Indicates if the operation was successful
message	string	Human-readable success message
publicUrl	string	Public URL to view the budget (no auth required)
budgetId	number	Internal budget ID
publicToken	string	Public token for accessing the budget

Response Status Codes

• 201 Created - Budget created successfully
• 400 Bad Request - Invalid request body or validation errors
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions
• 422 Unprocessable Entity - Business logic validation errors

Usage Example

// Create a budget and get a shareable link
const response = await fetch("https://api.billoget.com/v1/api/budgets/public", {
  method: "POST",
  headers: {
    Authorization: "Bearer bk_live_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    currency: "USD",
    issueDate: new Date().toISOString(),
    expirationDate: new Date(
      Date.now() + 30 * 24 * 60 * 60 * 1000
    ).toISOString(),
    customerId: 123,
    sellerId: 456,
    minimumPaymentToConfirm: 100.0,
    subtotal: 1000.0,
    total: 1210.0,
    iva: 210.0,
    items: [{ productId: 101, quantity: 2, unitPrice: 500.0 }],
  }),
});

const result = await response.json();
console.log(`Share this budget: ${result.publicUrl}`);
// Output: Share this budget: https://app.billoget.com/budget/123_abc789_xyz456

---

List Budgets

Retrieve a paginated list of budgets with optional filtering and sorting.

Request

GET /api/public/budgets

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (max: 100, default: 10)
status	string	No	Filter by status: PENDING, APPROVED, REJECTED, EXPIRED
customerId	string	No	Filter by customer ID
search	string	No	Search in notes and descriptions
minTotal	number	No	Minimum total amount
maxTotal	number	No	Maximum total amount
createdAfter	string	No	Created after date (ISO 8601 format)
createdBefore	string	No	Created before date (ISO 8601 format)
sort	string	No	Sort field: createdAt, total, status
order	string	No	Sort order: asc, desc (default: desc)

Example Request

curl -X GET "https://api.billoget.com/v1/api/public/budgets?page=1&limit=10&status=PENDING" \
  -H "Authorization: Bearer bk_live_your_api_key_here" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": "budget_123",
      "customerId": "customer_456",
      "status": "PENDING",
      "total": 1500.0,
      "subtotal": 1300.0,
      "tax": 200.0,
      "currency": "USD",
      "validUntil": "2024-02-15T23:59:59Z",
      "notes": "Q1 Marketing Budget",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "customer": {
        "id": "customer_456",
        "name": "Acme Corp",
        "email": "contact@acme.com"
      },
      "items": [
        {
          "id": "item_789",
          "productId": "product_101",
          "description": "Premium Marketing Package",
          "quantity": 2,
          "unitPrice": 500.0,
          "total": 1000.0
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasMore": false
  }
}

Response Status Codes

• 200 OK - Success
• 400 Bad Request - Invalid parameters
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions
• 429 Too Many Requests - Rate limit exceeded

---

Get Budget by ID

Retrieve a specific budget by its ID with full details including items.

Request

GET /api/public/budgets/{budgetId}

Path Parameters

Parameter	Type	Required	Description
budgetId	string	Yes	The unique budget identifier

Example Request

curl -X GET "https://api.billoget.com/v1/api/public/budgets/budget_123" \
  -H "Authorization: Bearer bk_live_your_api_key_here" \
  -H "Accept: application/json"

Response

{
  "data": {
    "id": "budget_123",
    "customerId": "customer_456",
    "status": "PENDING",
    "total": 1500.0,
    "subtotal": 1300.0,
    "tax": 200.0,
    "discount": 0.0,
    "currency": "USD",
    "validUntil": "2024-02-15T23:59:59Z",
    "notes": "Q1 Marketing Budget",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "customer": {
      "id": "customer_456",
      "name": "Acme Corp",
      "email": "contact@acme.com",
      "phone": "+1-555-123-4567"
    },
    "items": [
      {
        "id": "item_789",
        "productId": "product_101",
        "description": "Premium Marketing Package",
        "quantity": 2,
        "unitPrice": 500.0,
        "total": 1000.0,
        "product": {
          "id": "product_101",
          "name": "Premium Marketing Package",
          "sku": "MKT-PREM-001"
        }
      },
      {
        "id": "item_790",
        "productId": "product_102",
        "description": "Additional Services",
        "quantity": 1,
        "unitPrice": 300.0,
        "total": 300.0,
        "product": {
          "id": "product_102",
          "name": "Additional Services",
          "sku": "SRV-ADD-001"
        }
      }
    ],
    "metadata": {
      "source": "api",
      "campaign": "Q1_2024",
      "department": "marketing"
    }
  }
}

Response Status Codes

• 200 OK - Success
• 404 Not Found - Budget not found
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions

---

Create Budget

Create a new budget with items and customer information.

Request

POST /api/public/budgets

Request Body

{
  "customerId": "customer_456",
  "items": [
    {
      "productId": "product_789",
      "description": "Premium Marketing Package",
      "quantity": 2,
      "unitPrice": 500.0
    },
    {
      "productId": "product_790",
      "description": "Additional Services",
      "quantity": 1,
      "unitPrice": 200.0
    }
  ],
  "notes": "Q1 Marketing Campaign Budget",
  "validUntil": "2024-03-31T23:59:59Z",
  "currency": "USD",
  "taxRate": 0.15,
  "discountAmount": 0.0,
  "metadata": {
    "source": "api",
    "campaign": "Q1_2024",
    "department": "marketing"
  }
}

Request Body Schema

Field	Type	Required	Description
customerId	string	Yes	Customer ID for the budget
items	array	Yes	Array of budget items
items[].productId	string	No	Product ID (optional if custom item)
items[].description	string	Yes	Item description
items[].quantity	number	Yes	Item quantity
items[].unitPrice	number	Yes	Price per unit
notes	string	No	Additional notes
validUntil	string	No	Expiration date (ISO 8601)
currency	string	No	Currency code (default: USD)
taxRate	number	No	Tax rate (0.0 to 1.0)
discountAmount	number	No	Discount amount
metadata	object	No	Additional metadata

Example Request

curl -X POST "https://api.billoget.com/v1/api/public/budgets" \
  -H "Authorization: Bearer bk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_456",
    "items": [
      {
        "productId": "product_789",
        "description": "Premium Marketing Package",
        "quantity": 2,
        "unitPrice": 500.00
      }
    ],
    "notes": "Q1 Marketing Campaign Budget",
    "validUntil": "2024-03-31T23:59:59Z"
  }'

Response

{
  "data": {
    "id": "budget_124",
    "customerId": "customer_456",
    "status": "PENDING",
    "total": 1150.0,
    "subtotal": 1000.0,
    "tax": 150.0,
    "discount": 0.0,
    "currency": "USD",
    "validUntil": "2024-03-31T23:59:59Z",
    "notes": "Q1 Marketing Campaign Budget",
    "createdAt": "2024-01-16T14:30:00Z",
    "updatedAt": "2024-01-16T14:30:00Z",
    "items": [
      {
        "id": "item_791",
        "productId": "product_789",
        "description": "Premium Marketing Package",
        "quantity": 2,
        "unitPrice": 500.0,
        "total": 1000.0
      }
    ]
  }
}

Response Status Codes

• 201 Created - Budget created successfully
• 400 Bad Request - Invalid request body
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions
• 422 Unprocessable Entity - Validation errors

---

Update Budget

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

Request

PUT /api/public/budgets/{budgetId}

Path Parameters

Parameter	Type	Required	Description
budgetId	string	Yes	The unique budget identifier

Request Body

{
  "status": "APPROVED",
  "notes": "Approved by manager - ready to proceed",
  "validUntil": "2024-04-30T23:59:59Z",
  "items": [
    {
      "id": "item_789",
      "description": "Premium Marketing Package (Updated)",
      "quantity": 3,
      "unitPrice": 500.0
    }
  ]
}

Request Body Schema

Field	Type	Required	Description
status	string	No	Budget status: PENDING, APPROVED, REJECTED, EXPIRED
notes	string	No	Additional notes
validUntil	string	No	Expiration date (ISO 8601)
items	array	No	Array of budget items
taxRate	number	No	Tax rate (0.0 to 1.0)
discountAmount	number	No	Discount amount
metadata	object	No	Additional metadata

Example Request

curl -X PUT "https://api.billoget.com/v1/api/public/budgets/budget_123" \
  -H "Authorization: Bearer bk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "APPROVED",
    "notes": "Approved by manager - ready to proceed",
    "validUntil": "2024-04-30T23:59:59Z"
  }'

Response

{
  "data": {
    "id": "budget_123",
    "customerId": "customer_456",
    "status": "APPROVED",
    "total": 1500.0,
    "subtotal": 1300.0,
    "tax": 200.0,
    "currency": "USD",
    "validUntil": "2024-04-30T23:59:59Z",
    "notes": "Approved by manager - ready to proceed",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-16T16:45:00Z"
  }
}

Response Status Codes

• 200 OK - Budget updated successfully
• 400 Bad Request - Invalid request body
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Budget not found
• 422 Unprocessable Entity - Validation errors

---

Delete Budget

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

Request

DELETE /api/public/budgets/{budgetId}

Path Parameters

Parameter	Type	Required	Description
budgetId	string	Yes	The unique budget identifier

Example Request

curl -X DELETE "https://api.billoget.com/v1/api/public/budgets/budget_123" \
  -H "Authorization: Bearer bk_live_your_api_key_here"

Response

{
  "data": {
    "id": "budget_123",
    "status": "DELETED",
    "deletedAt": "2024-01-16T18:00:00Z"
  },
  "message": "Budget deleted successfully"
}

Response Status Codes

• 200 OK - Budget deleted successfully
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Budget not found

---

Budget Status Lifecycle

Understanding budget statuses and their transitions:

graph TD
    A[PENDING] --> B[APPROVED]
    A --> C[REJECTED]
    A --> D[EXPIRED]
    B --> E[COMPLETED]
    C --> A
    D --> A
    E --> F[ARCHIVED]

Status Descriptions

• PENDING: Budget is waiting for approval
• APPROVED: Budget has been approved and is active
• REJECTED: Budget has been rejected and needs revision
• EXPIRED: Budget has passed its expiration date
• COMPLETED: Budget has been completed and finalized
• ARCHIVED: Budget has been archived for historical purposes
• DELETED: Budget has been soft deleted

---

Error Handling

All endpoints return consistent error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "customerId",
        "message": "Customer ID is required"
      }
    ]
  }
}

Common Error Codes

• VALIDATION_ERROR - Request validation failed
• RESOURCE_NOT_FOUND - Requested resource not found
• UNAUTHORIZED - Invalid or missing authentication
• FORBIDDEN - Insufficient permissions
• RATE_LIMIT_EXCEEDED - Too many requests
• INTERNAL_ERROR - Server error

---

Rate Limiting

Budget API endpoints are subject to rate limiting:

• Default limit: 1000 requests per hour
• Burst limit: 100 requests per minute
• Headers: Check X-RateLimit-* headers in responses

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642694400

---

Next Steps

• Customers API - Manage customer information
• Products API - Handle product catalog
• Webhooks - Set up real-time notifications
• Postman Collection - Test these endpoints