> ## Documentation Index > Fetch the complete documentation index at: https://docs.meteroid.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a budget > Sets a spending limit for one currency the customer is billed in, with alerts at percentages of it, on the customer's whole spend or on one subscription's. A customer has one active budget per currency, and per subscription. Beta: the request and response shapes of this endpoint may change before general availability. ## OpenAPI ````yaml https://api.meteroid.com/api-docs/openapi.json post /api/v1/customers/{id_or_alias}/budgets openapi: 3.1.0 info: title: meteroid description: '' license: name: LicenseRef-Proprietary identifier: LicenseRef-Proprietary version: 0.1.0 servers: [] security: [] tags: - name: Meteroid description: Meteroid API - name: Add-ons - name: Batch Jobs - name: Budgets description: >- Beta: may change before general availability. Spending limits on a customer's usage, or one subscription's, per currency, with alerts at percentages of the amount. x-beta: true - name: Checkout Sessions - name: Checks description: >- Beta: may change before general availability. Whether a customer may consume more of a feature right now. x-beta: true - name: Connect description: Manage connected accounts (Express & Standard) - name: Coupons - name: Credit Notes - name: Credit units description: >- Custom denominations, such as "credits", that usage can be priced in and credit granted or sold in, instead of money. - name: Credits description: >- Prepaid credit: a customer's wallets, credit grants, ledger and top-ups. Promotional credit applies before tax like a discount; paid credit applies after tax like a payment. - name: Custom Properties - name: Customers - name: Entitlements - name: Events - name: Features - name: Invoices - name: Licenses description: >- Licenses for your customers' self-hosted installations: signed tokens carrying their plan's entitlements, activated and refreshed by the installation over the public licensing endpoints. - name: Metrics - name: OAuth description: OAuth 2.0 token endpoints (public, client-credentials auth) - name: OAuth Apps description: Manage OAuth applications for Connect integrations - name: Plans - name: Product Families - name: Products - name: Subscriptions - name: Usage - name: Usage costs description: >- Beta: may change before general availability. A customer's or a subscription's usage events and usage over time, with what they cost. x-beta: true - name: Webhook Endpoints description: Manage outbound webhook endpoints and inspect their deliveries paths: /api/v1/customers/{id_or_alias}/budgets: post: tags: - Budgets summary: Create a budget description: >- Sets a spending limit for one currency the customer is billed in, with alerts at percentages of it, on the customer's whole spend or on one subscription's. A customer has one active budget per currency, and per subscription. Beta: the request and response shapes of this endpoint may change before general availability. operationId: create_budget parameters: - name: id_or_alias in: path description: Customer ID or alias required: true schema: type: string - name: Idempotency-Key in: header description: Required; reuse it only to retry the same request required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBudgetRequest' required: true responses: '201': description: Budget created content: application/json: schema: $ref: '#/components/schemas/Budget' '400': description: >- Invalid request, a currency the customer (or the subscription) is not billed in, or a subscription that is not an active one of the customer content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '404': description: Customer not found content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '409': description: >- The customer already has a budget in that currency, or Idempotency-Key reused with another request content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' security: - bearer_auth: [] components: schemas: CreateBudgetRequest: type: object required: - amount properties: amount: type: integer format: int64 description: In minor units of the currency or credit unit. behavior: oneOf: - $ref: '#/components/schemas/BudgetBehavior' description: Defaults to SOFT. - type: 'null' credit_unit: type: - string - 'null' description: >- A credit unit (its code): the budget counts the usage priced in that unit, in its minor units. currency: oneOf: - $ref: '#/components/schemas/Currency' description: >- A currency the customer is billed in. Set exactly one of `currency` and `credit_unit`; a customer has one active budget per currency or credit unit, and per subscription. - type: 'null' subscription_id: type: - string - 'null' description: >- An active subscription of the customer (`sub_…`): the budget then counts only that subscription's spend, in its currency. Absent counts the whole customer's. thresholds: type: - array - 'null' items: type: integer format: int32 minimum: 0 description: >- Percentages of the amount (1 to 100, at most 10). Defaults to 50, 80 and 100. additionalProperties: false Budget: type: object description: >- A spending limit for one currency, set by you or by the customer, with alerts at percentages of it. It counts the customer's whole spend, or one subscription's. A HARD budget also refuses access once reached. A budget never charges the customer. required: - id - amount - thresholds - behavior - created_by - version - exact - created_at - updated_at properties: amount: type: integer format: int64 description: In minor units of the currency or credit unit. archived_at: type: - string - 'null' format: date-time as_of: type: - string - 'null' format: date-time description: When `estimated_spend` was last measured. behavior: $ref: '#/components/schemas/BudgetBehavior' created_at: type: string format: date-time created_by: $ref: '#/components/schemas/BudgetAuthor' credit_unit: type: - string - 'null' description: >- The credit unit (its code) whose usage the budget counts; absent for a currency. credit_unit_precision: type: - integer - 'null' format: int32 description: >- Decimal places of `credit_unit`: amounts are integers of 10^-precision credit. minimum: 0 currency: oneOf: - $ref: '#/components/schemas/Currency' description: >- The currency the budget counts spend in; absent for a budget in a credit unit. - type: 'null' estimated_spend: type: - integer - 'null' format: int64 description: >- Spend in the current billing period, including usage not invoiced yet, in minor units. Absent until first measured. exact: type: boolean description: 'Always false: the estimate prices usage that is not yet invoiced.' id: type: string period: oneOf: - $ref: '#/components/schemas/BudgetPeriod' description: >- The current billing period: of `subscription_id` when set. Absent for an archived budget, or without an active subscription to measure it on. - type: 'null' subscription_id: type: - string - 'null' description: >- The subscription whose spend the budget counts; null when it counts the whole customer's. thresholds: type: array items: type: integer format: int32 minimum: 0 description: Percentages of the amount at which an alert is sent. updated_at: type: string format: date-time version: type: integer format: int32 description: Send it back as `expected_version` when patching. RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string BudgetBehavior: type: string description: >- What reaching the amount does. A SOFT budget only sends alerts; a HARD budget also makes the entitlement check answer BUDGET_EXCEEDED for the features whose usage counts in its spend. A HARD budget on one subscription refuses the checks naming that subscription, and the checks naming none once every subscription charging the feature's metric is refused by its own. enum: - SOFT - HARD Currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLP - CNH - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL examples: - EUR BudgetAuthor: type: string description: >- Who set the budget: you (TENANT) or the customer, from the portal (CUSTOMER). enum: - TENANT - CUSTOMER BudgetPeriod: type: object required: - start properties: end: type: - string - 'null' format: date description: Absent when the period never ends. start: type: string format: date ErrorCode: type: string enum: - BAD_REQUEST - NOT_FOUND - CONFLICT - FORBIDDEN - UNAUTHORIZED - TOKEN_EXPIRED - TOO_MANY_REQUESTS - INTERNAL_SERVER_ERROR securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.