> ## Documentation Index > Fetch the complete documentation index at: https://docs.getlago.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a billing entity > This endpoint is used to create a new billing entity ## OpenAPI ````yaml POST /billing_entities openapi: 3.1.0 info: title: Lago API documentation description: >- Lago API allows your application to push customer information and metrics (events) from your application to the billing application. version: 1.45.2 license: name: AGPLv3 url: https://github.com/getlago/lago-openapi/blob/main/LICENSE contact: email: tech@getlago.com servers: - url: https://api.getlago.com/api/v1 description: US Lago cluster - url: https://api.eu.getlago.com/api/v1 description: EU Lago cluster security: - bearerAuth: [] tags: - name: activity_logs description: Everything about Activity logs externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/audit-logs/activity-logs-object - name: analytics description: Everything about Analytics - name: api_logs description: Everything about API logs externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/audit-logs/api-logs-object - name: billable_metrics description: Everything about Billable metric collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/billable-metrics/object - name: features description: Everything about Feature collection externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/entitlements/features/feature-object - name: entitlements description: Everything about Entitlement collection externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/entitlements/plan-entitlements/plan-entitlement-object - name: billing_entities description: Everything about Billing Entities externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/billing-entities/object - name: customers description: Everything about Customer collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/customers/object - name: plans description: Everything about Plan collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/plans/object - name: subscriptions description: Everything about Subscription collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/subscriptions/subscription-object - name: events description: Everything about Event collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/events/event-object - name: organizations description: Everything about Organization collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/organizations/organization-object - name: taxes description: Everything about Tax collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/taxes/tax-object - name: coupons description: Everything about Coupon collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/coupons/coupon-object - name: add_ons description: Everything about Add-on collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/add-ons/add-on-object - name: fees description: Everything about Fees externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/invoices/invoice-object#fee-object - name: invoices description: Everything about Invoice collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/invoices/invoice-object - name: wallets description: Everything about Wallet collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/wallets/wallet-object - name: credit_notes description: Everything about Credit notes collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/credit-notes/credit-note-object - name: webhooks description: Everything about Webhooks externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/webhooks/format---signature#1-retrieve-the-public-key - name: webhook_endpoints description: Everything about Webhook Endpoints externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/webhook-endpoints/webhook-endpoint-object - name: payment_receipts description: Everything about Payment receipts externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/payment-receipts/payment-receipt-object - name: payment_requests description: Everything about PaymentRequests externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/payment-requests/payment-request-object - name: payments description: Everything about Payments externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/payments/payment-object - name: payment_methods description: Everything about Payment Methods externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/payment-methods/payment-method-object externalDocs: description: Lago Github url: https://github.com/getlago paths: /billing_entities: post: tags: - billing_entities summary: Create a billing entity description: This endpoint is used to create a new billing entity operationId: createBillingEntity requestBody: description: The billing entity payload content: application/json: schema: $ref: '#/components/schemas/BillingEntityCreateInput' required: true responses: '200': description: Billing entity created content: application/json: schema: $ref: '#/components/schemas/BillingEntityObject' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/UnprocessableEntity' components: schemas: BillingEntityCreateInput: type: object description: Billing entity create input required: - billing_entity properties: billing_entity: type: object required: - code - name properties: code: type: string example: acme_corp description: The unique code of the billing entity name: type: string example: Acme Corp description: The name of the billing entity default_currency: $ref: '#/components/schemas/Currency' description: The default currency of the billing entity example: USD document_numbering: type: string enum: - per_customer - per_billing_entity description: >- The type of document numbering for this billing entity: - `per_customer`: document numbers are unique per customer - `per_billing_entity`: document numbers are unique per billing entity document_number_prefix: type: - string - 'null' example: ABC-123 description: The prefix used in document numbers for this billing entity finalize_zero_amount_invoice: type: boolean example: true description: >- Whether to finalize invoices with zero amount for this billing entity billing_configuration: type: object properties: invoice_footer: type: string example: Thank you for your business description: >- The footer text to be displayed on invoices for this billing entity document_locale: type: string example: en description: >- The language of the documents generated for this billing entity invoice_grace_period: type: integer example: 0 description: The grace period (in days) for invoice finalization subscription_invoice_issuing_date_anchor: type: string description: >- Defines whether the issuing date follows the current billing period's end date or the next period starting date. enum: - current_period_end - next_period_start default: next_period_start subscription_invoice_issuing_date_adjustment: type: string description: >- The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period. enum: - align_with_finalization_date - keep_anchor default: align_with_finalization_date net_payment_term: type: integer example: 0 description: The net payment term (in days) for this billing entity address_line1: type: - string - 'null' example: 5230 Penfield Ave description: The first line of the billing address address_line2: type: - string - 'null' example: Suite 100 description: The second line of the billing address city: type: - string - 'null' example: Woodland Hills description: The city of the billing address state: type: - string - 'null' example: CA description: The state of the billing address country: $ref: '#/components/schemas/Country' description: The country code of the billing address nullable: true zipcode: type: - string - 'null' example: '91364' description: The zipcode of the billing address email: type: - string - 'null' format: email example: billing@acme.com description: The email address of the billing entity legal_name: type: - string - 'null' example: Acme Corporation description: The legal name of the billing entity legal_number: type: - string - 'null' example: US123456789 description: The legal registration number of the billing entity tax_identification_number: type: - string - 'null' example: EU123456789 description: The tax identification number of the billing entity timezone: $ref: '#/components/schemas/Timezone' description: The timezone of the billing entity example: UTC email_settings: type: array items: type: string enum: - invoice.finalized - credit_note.created description: The email notification settings for this billing entity eu_tax_management: type: boolean example: false description: Whether EU tax management is enabled for this billing entity logo: type: - string - 'null' format: uri example: data:image/png;base64,... description: The base64 encoded logo image for the billing entity BillingEntityObject: type: object description: Billing entity object required: - lago_id - code - name - default_currency - document_locale - document_numbering - finalize_zero_amount_invoice - invoice_grace_period - net_payment_term - timezone - created_at - updated_at properties: lago_id: type: string format: uuid example: 1a901a90-1a90-1a90-1a90-1a901a901a90 description: A unique identifier for the billing entity in the Lago application code: type: string example: acme_corp description: The unique code of the billing entity name: type: string example: Acme Corp description: The name of the billing entity default_currency: $ref: '#/components/schemas/Currency' description: The default currency of the billing entity example: USD document_locale: type: string example: en description: The language of the documents generated for this billing entity document_numbering: type: string enum: - per_customer - per_billing_entity description: >- The type of document numbering for this billing entity: - `per_customer`: document numbers are unique per customer - `per_billing_entity`: document numbers are unique per billing entity example: per_customer document_number_prefix: type: - string - 'null' example: ABC-123 description: The prefix used in document numbers for this billing entity finalize_zero_amount_invoice: type: boolean example: true description: >- Whether to finalize invoices with zero amount for this billing entity invoice_footer: type: - string - 'null' example: Thank you for your business description: The footer text to be displayed on invoices for this billing entity invoice_grace_period: type: integer example: 0 description: The grace period (in days) for invoice finalization subscription_invoice_issuing_date_anchor: type: string description: >- Defines whether the issuing date follows the current billing period's end date or the next period starting date. enum: - current_period_end - next_period_start default: next_period_start subscription_invoice_issuing_date_adjustment: type: string description: >- The logic applied on top of the subscription_invoice_issuing_date_anchor rule. You can opt to use the invoice finalization date, that includes any configured grace period. enum: - align_with_finalization_date - keep_anchor default: align_with_finalization_date is_default: type: boolean example: false description: >- Whether this billing entity is the default billing entity for the organization. Default billing entity will be used as fallback in services if no billing entity is specified when billing_entity is not provided. Default billing entity is the billing entity that will be used to generate invoices if no billing entity is specified when invoice is created. is the oldest active billing entity and this flag cannot be changed net_payment_term: type: integer example: 0 description: The net payment term (in days) for this billing entity address_line1: type: - string - 'null' example: 5230 Penfield Ave description: The first line of the billing address address_line2: type: - string - 'null' example: Suite 100 description: The second line of the billing address city: type: - string - 'null' example: Woodland Hills description: The city of the billing address state: type: - string - 'null' example: CA description: The state of the billing address country: $ref: '#/components/schemas/Country' description: The country code of the billing address nullable: true zipcode: type: - string - 'null' example: '91364' description: The zipcode of the billing address email: type: - string - 'null' format: email example: billing@acme.com description: The email address of the billing entity legal_name: type: - string - 'null' example: Acme Corporation description: The legal name of the billing entity legal_number: type: - string - 'null' example: US123456789 description: The legal registration number of the billing entity tax_identification_number: type: - string - 'null' example: EU123456789 description: The tax identification number of the billing entity timezone: $ref: '#/components/schemas/Timezone' description: The timezone of the billing entity example: UTC email_settings: type: array items: type: string enum: - invoice.finalized - credit_note.created - payment_receipt.created description: The email notification settings for this billing entity eu_tax_management: type: boolean example: false description: Whether EU tax management is enabled for this billing entity logo_url: type: - string - 'null' format: uri example: https://getlago.com/logo.png description: The URL of the billing entity's logo created_at: type: string format: date-time example: '2022-04-29T08:59:51Z' description: The date and time when the billing entity was created updated_at: type: string format: date-time example: '2022-04-29T08:59:51Z' description: The date and time when the billing entity was last updated Currency: type: string example: USD enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BIF - BMD - BND - BOB - BRL - BSD - BWP - BYN - BZD - CAD - CDF - CHF - CLF - CLP - CNY - COP - CRC - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - ISK - JMD - JPY - KES - KGS - KHR - KMF - KRW - KYD - KZT - LAK - LBP - LKR - LRD - LSL - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SEK - SGD - SHP - SLL - SOS - SRD - STD - SZL - THB - TJS - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW Country: type: string example: US enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW Timezone: type: string example: America/Los_Angeles enum: - UTC - Africa/Algiers - Africa/Cairo - Africa/Casablanca - Africa/Harare - Africa/Johannesburg - Africa/Monrovia - Africa/Nairobi - America/Argentina/Buenos_Aires - America/Bogota - America/Caracas - America/Chicago - America/Chihuahua - America/Denver - America/Guatemala - America/Guyana - America/Halifax - America/Indiana/Indianapolis - America/Juneau - America/La_Paz - America/Lima - America/Los_Angeles - America/Mazatlan - America/Mexico_City - America/Monterrey - America/Montevideo - America/New_York - America/Nuuk - America/Phoenix - America/Puerto_Rico - America/Regina - America/Santiago - America/Sao_Paulo - America/St_Johns - America/Tijuana - Asia/Almaty - Asia/Baghdad - Asia/Baku - Asia/Bangkok - Asia/Chongqing - Asia/Colombo - Asia/Dhaka - Asia/Hong_Kong - Asia/Irkutsk - Asia/Jakarta - Asia/Jerusalem - Asia/Kabul - Asia/Kamchatka - Asia/Karachi - Asia/Kathmandu - Asia/Kolkata - Asia/Krasnoyarsk - Asia/Kuala_Lumpur - Asia/Kuwait - Asia/Magadan - Asia/Muscat - Asia/Novosibirsk - Asia/Riyadh - Asia/Seoul - Asia/Shanghai - Asia/Singapore - Asia/Srednekolymsk - Asia/Taipei - Asia/Tashkent - Asia/Tbilisi - Asia/Tehran - Asia/Tokyo - Asia/Ulaanbaatar - Asia/Urumqi - Asia/Vladivostok - Asia/Yakutsk - Asia/Yangon - Asia/Yekaterinburg - Asia/Yerevan - Atlantic/Azores - Atlantic/Cape_Verde - Atlantic/South_Georgia - Australia/Adelaide - Australia/Brisbane - Australia/Darwin - Australia/Hobart - Australia/Melbourne - Australia/Perth - Australia/Sydney - Europe/Amsterdam - Europe/Athens - Europe/Belgrade - Europe/Berlin - Europe/Bratislava - Europe/Brussels - Europe/Bucharest - Europe/Budapest - Europe/Copenhagen - Europe/Dublin - Europe/Helsinki - Europe/Istanbul - Europe/Kaliningrad - Europe/Kyiv - Europe/Lisbon - Europe/Ljubljana - Europe/London - Europe/Madrid - Europe/Minsk - Europe/Moscow - Europe/Paris - Europe/Prague - Europe/Riga - Europe/Rome - Europe/Samara - Europe/Sarajevo - Europe/Skopje - Europe/Sofia - Europe/Stockholm - Europe/Tallinn - Europe/Vienna - Europe/Vilnius - Europe/Volgograd - Europe/Warsaw - Europe/Zagreb - Europe/Zurich - GMT+12 - Pacific/Apia - Pacific/Auckland - Pacific/Chatham - Pacific/Fakaofo - Pacific/Fiji - Pacific/Guadalcanal - Pacific/Guam - Pacific/Honolulu - Pacific/Majuro - Pacific/Midway - Pacific/Noumea - Pacific/Pago_Pago - Pacific/Port_Moresby - Pacific/Tongatapu ApiErrorBadRequest: type: object required: - status - error properties: status: type: integer format: int32 example: 400 error: type: string example: Bad request ApiErrorUnauthorized: type: object required: - status - error properties: status: type: integer format: int32 example: 401 error: type: string example: Unauthorized ApiErrorForbidden: type: object required: - status - error - code properties: status: type: integer format: int32 example: 403 error: type: string example: Forbidden code: type: string example: feature_unavailable ApiErrorUnprocessableEntity: type: object required: - status - error - code - error_details properties: status: type: integer format: int32 example: 422 error: type: string example: Unprocessable entity code: type: string example: validation_errors error_details: type: object responses: BadRequest: description: Bad Request error content: application/json: schema: $ref: '#/components/schemas/ApiErrorBadRequest' Unauthorized: description: Unauthorized error content: application/json: schema: $ref: '#/components/schemas/ApiErrorUnauthorized' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiErrorForbidden' UnprocessableEntity: description: Unprocessable entity error content: application/json: schema: $ref: '#/components/schemas/ApiErrorUnprocessableEntity' securitySchemes: bearerAuth: type: http scheme: bearer ````