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 successfully400 Bad Request
- Invalid request body or validation errors401 Unauthorized
- Invalid or missing API key403 Forbidden
- Insufficient permissions422 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
- Success400 Bad Request
- Invalid parameters401 Unauthorized
- Invalid or missing API key403 Forbidden
- Insufficient permissions429 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
- Success404 Not Found
- Budget not found401 Unauthorized
- Invalid or missing API key403 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 successfully400 Bad Request
- Invalid request body401 Unauthorized
- Invalid or missing API key403 Forbidden
- Insufficient permissions422 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 successfully400 Bad Request
- Invalid request body401 Unauthorized
- Invalid or missing API key403 Forbidden
- Insufficient permissions404 Not Found
- Budget not found422 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 successfully401 Unauthorized
- Invalid or missing API key403 Forbidden
- Insufficient permissions404 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 failedRESOURCE_NOT_FOUND
- Requested resource not foundUNAUTHORIZED
- Invalid or missing authenticationFORBIDDEN
- Insufficient permissionsRATE_LIMIT_EXCEEDED
- Too many requestsINTERNAL_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