--- title: "Create BillJob" method: POST path: "/organizations/{orgId}/billjobs" tags: ["BillJob"] --- # Create BillJob `POST /organizations/{orgId}/billjobs` Create a new BillJob to handle asynchronous bill calculations for a specific Organization. This operation allows you to initiate the processing of bills according to specified parameters. For example, create a BillJob to run only those bills where `billingFrequency` is `MONTHLY`. Note that if you want to run a BillJob for all billing frequencies, simply omit the `billingFrequency` request parameter. Once created, the BillJob's progress can be monitored: - In the Running Tasks panel in the m3ter Console - for more details, see [Running Bills Manually](https://www.m3ter.com/docs/guides/billing-and-usage-data/running-viewing-and-managing-bills/running-bills-and-viewing-bill-details#running-bills-manually) - Queried using the [List BillJobs](https://www.m3ter.com/docs/api#tag/BillJob/operation/ListBillJobs) operation. **NOTES:** - **Consolidated bills**. If you've already run billing with the Consolidate bills option disabled for your Organization but you then enable it, subsequent Bills for specific bill dates will now start afresh and not update earlier non-consolidated Bills for the same bill date. To avoid any billing conflicts, you might want to archive these earlier versions or delete them entirely. - **Maximum concurrent BillJobs**. If you already have 10 BillJobs currently running, and try to create another one, you'll get an HTTP 429 response (Too many requests). When one of the existing BillJobs has completed, you'll be able to submit another job ## Path parameters - `orgId` string, required ## Request body - BillJobRequest - `version` integer — The version number of the entity: - **Create entity:** Not valid for initial insertion of new entity - *do not use for Create*. On initial Create, version is set at 1 and listed in the response. - **Update Entity:** On Update, version is required and must match the existing version because a check is performed to ensure sequential versioning is preserved. Version is incremented by 1 and listed in the response. - `lastDateInBillingPeriod` string, date — Specifies the date *(in ISO 8601 format)* of the last day in the billing period, defining the time range for the associated Bills. For example: `"2023-03-24"`. - `billingFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUALLY' | 'AD_HOC' — Defines how often Bills are generated. - **Daily**. Starting at midnight each day, covering a twenty-four hour period following. - **Weekly**. Starting at midnight on a Monday morning covering the seven-day period following. - **Monthly**. Starting at midnight on the morning of the first day of each month covering the entire calendar month following. - **Annually**. Starting at midnight on the morning of the first day of each year covering the entire calendar year following. - **Ad_Hoc**. Use this setting when a custom billing schedule is used for billing an Account, such as for billing of Prepayment/Commitment fees using a custom billing schedule. - `billFrequencyInterval` integer — How often Bills are issued - used in conjunction with `billingFrequency`. For example, if `billingFrequency` is set to Monthly and `billFrequencyInterval` is set to 3, Bills are issued every three months. - `billDate` string, date — The specific billing date *(in ISO 8601 format)*, determining when the Bill was generated. For example: `"2023-01-24"`. - `externalInvoiceDate` string, date — For accounting purposes, the date set at Organization level to use for external invoicing with respect to billing periods - two options: * `FIRST_DAY_OF_NEXT_PERIOD` *(Default)*. Used when you want to recognize usage revenue in the following period. * `LAST_DAY_OF_ARREARS`. Used when you want to recognize usage revenue in the same period that it's consumed, instead of in the following period. For example, if the retrieved Bill was on a monthly billing frequency and the billing period for the Bill is September 2023 and the *External invoice date* is set at `FIRST_DAY_OF_NEXT_PERIOD`, then the `externalInvoiceDate` will be `"2023-10-01"`. **NOTE:** To change the `externalInvoiceDate` setting for your Organization, you can use the [Update OrganizationConfig](https://www.m3ter.com/docs/api#tag/OrganizationConfig/operation/GetOrganizationConfig) call. - `dueDate` string, date — The due date *(in ISO 8601 format)* for payment of the Bill. For example: `"2023-02-24"`. - `accountIds` string[] — An array of UUIDs representing the end customer Accounts associated with the BillJob. - `targetCurrency` string — The currency code used for the Bill, such as USD, GBP, or EUR. - `currencyConversions` CurrencyConversion[] — An array of currency conversion rates from Bill currency to Organization currency. For example, if Account is billed in GBP and Organization is set to USD, Bill line items are calculated in GBP and then converted to USD using the defined rate. - `from` string, required — Currency to convert from. For example: GBP. - `to` string, required — Currency to convert to. For example: USD. - `multiplier` number, double — Conversion rate between currencies. - `timezone` string — Specifies the time zone used for the generated Bills, ensuring alignment with the local time zone. - `yearEpoch` string, date — The starting date *(epoch)* for Yearly billing frequency *(in ISO 8601 format)*, determining the first Bill date for yearly Bills. - `monthEpoch` string, date — The starting date *(epoch)* for Monthly billing frequency *(in ISO 8601 format)*, determining the first Bill date for monthly Bills. - `weekEpoch` string, date — The starting date *(epoch)* for Weekly billing frequency *(in ISO 8601 format)*, determining the first Bill date for weekly Bills. - `dayEpoch` string, date — The starting date *(epoch)* for Daily billing frequency *(in ISO 8601 format)*, determining the first Bill date for daily Bills. ## Response `200` Returns the details of the created BillJob - BillJobResponse - `id` string, required — The UUID of the entity. - `version` integer — The version number: - **Create:** On initial Create to insert a new entity, the version is set at 1 in the response. - **Update:** On successful Update, the version is incremented by 1 in the response. - `lastDateInBillingPeriod` string, date — Specifies the date *(in ISO 8601 format)* of the last day in the billing period, defining the time range for the associated Bills. For example: `"2023-03-24"`. - `billingFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUALLY' | 'AD_HOC' — Defines how often Bills are generated. - **Daily**. Starting at midnight each day, covering a twenty-four hour period following. - **Weekly**. Starting at midnight on a Monday morning covering the seven-day period following. - **Monthly**. Starting at midnight on the morning of the first day of each month covering the entire calendar month following. - **Annually**. Starting at midnight on the morning of the first day of each year covering the entire calendar year following. - **Ad_Hoc**. Use this setting when a custom billing schedule is used for billing an Account, such as for billing of Prepayment/Commitment fees using a custom billing schedule. - `billFrequencyInterval` integer — How often Bills are issued - used in conjunction with `billingFrequency`. For example, if `billingFrequency` is set to Monthly and `billFrequencyInterval` is set to 3, Bills are issued every three months. - `billDate` string, date — The specific billing date *(in ISO 8601 format)*, determining when the Bill was generated. For example: `"2023-01-24"`. - `externalInvoiceDate` string, date — For accounting purposes, the date set at Organization level to use for external invoicing with respect to billing periods - two options: * `FIRST_DAY_OF_NEXT_PERIOD` *(Default)*. Used when you want to recognize usage revenue in the following period. * `LAST_DAY_OF_ARREARS`. Used when you want to recognize usage revenue in the same period that it's consumed, instead of in the following period. For example, if the retrieved Bill was on a monthly billing frequency and the billing period for the Bill is September 2023 and the *External invoice date* is set at `FIRST_DAY_OF_NEXT_PERIOD`, then the `externalInvoiceDate` will be `"2023-10-01"`. - `dueDate` string, date — The due date *(in ISO 8601 format)* for payment of the Bill. For example: `"2023-02-24"`. - `accountIds` string[] — An array of UUIDs representing the end customer Accounts associated with the BillJob. - `billIds` string[] — An array of Bill IDs related to the BillJob, providing references to the specific Bills generated. - `targetCurrency` string — The currency code used for the Bill, such as USD, GBP, or EUR. - `currencyConversions` CurrencyConversion[] — An array of currency conversion rates from Bill currency to Organization currency. For example, if Account is billed in GBP and Organization is set to USD, Bill line items are calculated in GBP and then converted to USD using the defined rate. - `from` string, required — Currency to convert from. For example: GBP. - `to` string, required — Currency to convert to. For example: USD. - `multiplier` number, double — Conversion rate between currencies. - `timezone` string — Specifies the time zone used for the generated Bills, ensuring alignment with the local time zone. - `yearEpoch` string, date — The starting date *(epoch)* for Yearly billing frequency *(in ISO 8601 format)*, determining the first Bill date for yearly Bills. - `monthEpoch` string, date — The starting date *(epoch)* for Monthly billing frequency *(in ISO 8601 format)*, determining the first Bill date for monthly Bills. - `weekEpoch` string, date — The starting date *(epoch)* for Weekly billing frequency *(in ISO 8601 format)*, determining the first Bill date for weekly Bills. - `dayEpoch` string, date — The starting date *(epoch)* for Daily billing frequency *(in ISO 8601 format)*, determining the first Bill date for daily Bills. - `status` 'PENDING' | 'INITIALIZING' | 'RUNNING' | 'COMPLETE' | 'CANCELLED' — The current status of the BillJob, indicating its progress or completion state. - `total` integer — The total number of Bills or calculations related to the BillJob. - `pending` integer — The number of pending actions or calculations within the BillJob. - `type` 'CREATE' | 'RECALCULATE' — Specifies the type of BillJob. * **Create** when creating a new Bill. * **Recalculate** when recalculating an existing Bill. - `dtCreated` string, date-time — The date and time *(in ISO 8601 format)* when the BillJob was first created. - `dtLastModified` string, date-time — The date and time *(in ISO 8601 format)* when the BillJob was last modified. - `createdBy` string — The unique identifier (UUID) for the user who created the BillJob. - `lastModifiedBy` string — The unique identifier (UUID) for the user who last modified this BillJob. ## Other responses - `4XX` — Error message - `5XX` — Error message --- [API](https://skmtc.net/m3ter-com/apis/m3ter-api.md) · [All operations](https://skmtc.net/m3ter-com/apis/m3ter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/m3ter-com/m3ter-api/revisions/ac93d1a9e6d9/schema)