--- title: "Retrieve Bills in Billing Period" method: GET path: "/organizations/{orgId}/bills/billingperiod/{lastDateInBillingPeriod}/{billingFrequency}" tags: ["Bill"] --- # Retrieve Bills in Billing Period `GET /organizations/{orgId}/bills/billingperiod/{lastDateInBillingPeriod}/{billingFrequency}` ## Request - Base URL: `https://api.m3ter.com` - URL: `https://api.m3ter.com/organizations/{orgId}/bills/billingperiod/{lastDateInBillingPeriod}/{billingFrequency}` - Auth: OAuth 2 - Authorization code: `https://m3ter.auth.us-east-1.amazoncognito.com/oauth2/authorize`, token URL `https://m3ter.auth.us-east-1.amazoncognito.com/oauth2/token` - Client credentials, token URL `/oauth/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieve all Bills within a specified billing period. This endpoint allows you to retrieve Bills on various frequencies, such as daily, weekly, monthly, or annually. Specify the last day of the period to define the range. For example, to retrieve all Bills on monthly billing up to September with due date of 1st of month, use the last day of September, which is September 30th. The list can also be paginated for easier management. ## Path parameters - `orgId` string, required - `lastDateInBillingPeriod` string, required - `billingFrequency` string, required ## Query parameters - `pageSize` integer - `nextToken` string - `additional` string[] ## Response `200` Returns the list of Bills within the billing period - PaginatedBillResponseData - `data` BillResponse[] - `lineItems` BillLineItem[]: An array of the Bill line items. - `id` string: The UUID for the line item. - `productId` string: The UUID of the Product for the line item. - `productName` string: The name of the Product for the line item. - `productCode` string - `accountingProductId` string - `accountingProductName` string - `accountingProductCode` string - `aggregationId` string: The Aggregation ID used for the line item. - `compoundAggregationId` string: The Compound Aggregation ID for the line item if a Compound Aggregation has been used. - `counterId` string - `chargeId` string - `segment` object: Applies only when segmented Aggregations have been used. The Segment to which the usage data in this line item belongs. - `group` object - `meterId` string: The UUID of the Meter used in the line item. - `planId` string: The ID of the Plan used for the line item. - `planGroupId` string: The UUID of the PlanGroup, provided the line item used a PlanGroup. - `commitmentId` string: If Commitments *(prepayments)* are used in the line item, this shows the Commitment UUID. - `balanceId` string - `description` string, required: Line item description. - `quantity` number, required: The amount of usage for the line item. - `units` number, required: The number of units used for the line item. - `unit` string, required: The unit for the usage data in thie line item. For example: **GB** of disk storage space. - `subtotal` number, required: The subtotal amount for the line item, before any currency conversions. - `currency` string, required: The currency code for the currency used in the line item. For example: USD, GBP, or EUR. - `conversionRate` number, required: The currency conversion rate if currency conversion is required for the line item. - `convertedSubtotal` number, required: The converted subtotal amount if currency conversions have been used. - `creditTypeId` string - `lineItemType` 'STANDING_CHARGE' | 'USAGE' | 'COUNTER_RUNNING_TOTAL_CHARGE' | 'COUNTER_ADJUSTMENT_DEBIT' | 'COUNTER_ADJUSTMENT_CREDIT' | 'USAGE_CREDIT' | 'MINIMUM_SPEND' | 'MINIMUM_SPEND_REFUND' | 'CREDIT_DEDUCTION' | 'MANUAL_ADJUSTMENT' | 'CREDIT_MEMO' | 'DEBIT_MEMO' | 'COMMITMENT_CONSUMED' | 'COMMITMENT_FEE' | 'OVERAGE_SURCHARGE' | 'OVERAGE_USAGE' | 'BALANCE_CONSUMED' | 'BALANCE_FEE' | 'AD_HOC', required: See [Bill Line Item Types](https://www.m3ter.com/docs/guides/running-viewing-and-managing-bills/bill-line-item-types) for more information. - `pricingId` string: The UUID of the Pricing used on the line item. - `childAccountId` string: If part of a Parent/Child account billing hierarchy, this is the child Account UUID. - `childAccountCode` string: If part of a Parent/Child account billing hierarchy, this is the code for the child Account. - `usagePerPricingBand` BillLineItemPricingBandUsage[]: Shows the usage by pricing band for tiered pricing structures. - `pricingBandId` string: The UUID for the pricing band. - `lowerLimit` number, double: The lower limit *(start)* of the pricing band. - `fixedPrice` number: Fixed price is a charge entered for certain pricing types such as Stairstep, Custom Tiered, and Custom Volume. It is a set price and not dependent on usage. - `unitSubtotal` number: The subtotal of the unit usage. - `unitPrice` number: The price per unit in the band. - `bandUnits` number: The number of units used within the band. - `bandQuantity` number: Usage amount within the band. - `bandSubtotal` number: Subtotal amount for the band. - `creditTypeId` string: The UUID of the credit type. - `convertedBandSubtotal` number - `servicePeriodStartDate` string, date-time: The starting date *(inclusive)* for the service period *(in ISO 8601 format)*. - `servicePeriodEndDate` string, date-time: The ending date *(exclusive)* for the service period *(in ISO 8601 format)*. - `referencedBillId` string - `referencedLineItemId` string - `reasonId` string - `contractId` string: The UUID for the Contract used in the line item. - `averageUnitPrice` number, required: The average unit price across all tiers / pricing bands. - `sequenceNumber` integer: The number used for sequential invoices. - `additional` object - `grantDrawdowns` GrantDrawdown[] - `balanceId` string - `quantity` number - `units` number - `currencyAmount` number - `balanceDrawdowns` BalanceDrawdown[] - `balanceId` string - `units` number - `balanceAmount` number - `lineItemAmount` number - `billAmount` number - `commitmentDrawdowns` CommitmentDrawdown[] - `commitmentId` string - `units` number - `commitmentAmount` number - `lineItemAmount` number - `billAmount` number - `creditCoverage` CreditCoverage[] - `lineItemId` string - `units` number - `lineItemAmount` number - `creditAmount` number - `billAmount` number - `purchaseOrderNumber` string: Purchase Order number linked to the Account the Bill is for. - `externalInvoiceReference` string: The reference ID to use for external invoice. - `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)*. * `LAST_DAY_OF_ARREARS` 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://docs.m3ter.com/api/organizationconfig/update-organizationconfig) call. - `jsonStatementGenerated` boolean: Flag to indicate that the statement in JSON format has been generated for the Bill. * **TRUE** - JSON statement has been generated. * **FALSE** - no JSON statement generated. - `csvStatementGenerated` boolean: Flag to indicate that the statement in CSV format has been generated for the Bill. * **TRUE** - CSV statement has been generated. * **FALSE** - no CSV statement generated. - `statementStale` boolean: True if the existing bill statement (JSON or CSV) is marked as stale/outdated. - `billTotal` number: The sum total for the Bill. - `totalDebits` number: The sum of debit line items on the bill. - `totalCredits` number: The absolute sum of credit line items on the bill. - `sequentialInvoiceNumber` string: The sequential invoice number of the Bill. **NOTE:** If you have not defined a `billPrefix` for your Organization, a `sequentialInvoiceNumber` is not returned in the response. See [Update OrganizationConfig](https://docs.m3ter.com/api/organizationconfig/update-organizationconfig) - `dtCreated` string, date-time: The date and time *(in ISO 8601 format)* when the Bill was first created. - `dtLastModified` string, date-time: The date and time *(in ISO 8601 format)* when the Bill was last modified. - `createdBy` string: The unique identifier (UUID) for the user who created the Bill. - `lastModifiedBy` string: The unique identifier (UUID) for the user who last modified this Bill. - `dtApproved` string, date-time: The DateTime when the bill was approved. - `approvedBy` string: The id of the user who approved this bill. - `dtLocked` string, date-time: The DateTime when the bill was locked. - `lockedBy` string: The id of the user who locked this bill. - `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. - `accountId` string: The unique identifier (UUID) of the Account the Bill was generated for. - `accountCode` string: The short code of the Account the Bill was generated for. - `startDate` string, date - `endDate` string, date - `startDateTimeUTC` string, date-time: Specifies the UTC time zone start date/time of the Bill's period in ISO 8601 format. Start dates are inclusive. For example: `"2022-02-01T00:00:00.000Z"`. - `endDateTimeUTC` string, date-time: Specifies the UTC time zone end date/time of the Bill's period in ISO 8601 format. End dates are exclusive. For example: `"2022-03-01T00:00:00.000Z"`. - `billDate` string, date: Based on the Billing cycle. Typically the first day of each Billing period. Bill date is determined by Organization Epoch setting for first Bill date and subsequent Bill dates and combined with the defined billing frequency - daily, weekly, monthly, or yearly. For example: `"2022-05-01"`. Note that the Organization Epoch settings for first Bill date can be overridden at Account and Plan level. - `dueDate` string, date: Date the Bill is due. Determined by `daysBeforeBillDue` Organization setting and `billDate`. For example, if `billDate` for monthly billing cycle is 1st of each month and `daysBeforeBillDue` = 10, then `dueDate` = 11th of each month. For example: `"2022-05-11"`. - `billingFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'ANNUALLY' | 'AD_HOC' | 'MIXED': 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 the Bill is created. If `billingFrequency` is MONTHLY and `billFrequencyInterval` is 3, then the Bill is created every three months. - `timezone` string: The time zone used for the generated Bill. - `currency` string: Bill Currency code. For example: USD, GBP or EUR. - `locked` boolean: Boolean flag indicating whether the Bill is in a locked state. A locked a Bill can no longer be changed and is excluded from any billing runs: * **TRUE** - Bill is locked. * **FALSE** - Bill is unlocked. - `createdDate` string, date-time: Date/time the Bill was first calculated *(in ISO 8601 format)*. - `status` 'PENDING' | 'APPROVED': Indicates whether the Bill has passed human/manual approval. * **Pending** - Bill has not yet been passed by a human reviewer. * **Approved** - Bill has been approved after manual review. - `billJobId` string: The unique identifier (UUID) of the BillJob responsible for generating the Bill. - `currencyConversions` CurrencyConversion[]: Currency conversion rates. The currency selected for your Organization determines the *billing currency*. This billing currency can differ from the *pricing currency* used when pricing Product Plans attached to end-customer Accounts: * For example, if an Account is priced in GBP and Organization billing currency is set to USD, Bill line items are calculated in GBP and then converted to USD using the defined currency conversion rate. If you intend to use different billing and pricing currencies, you must define currency conversion rates - `from` string, required: Currency to convert from. For example: EUR. - `to` string, required: Currency to convert to. For example: USD. - `multiplier` number, double: Conversion rate between currencies. - `lastCalculatedDate` string, date-time: Date the Bill was last calculated *(in ISO 8601 format)*. - `nextToken` string ## Other responses - `4XX`: Error message - `5XX`: Error message ## Changes - **2026-10-16** `85c514abc692`: 1 breaking, 6 info - the `data/items/allOf[#/components/schemas/AbstractBillResponse]/allOf[subschema #2]/` response's property type changed from no type to `object` for status `200` - added the optional property `data/items/lineItems/items/balanceDrawdowns` to the response with the `200` status - added the optional property `data/items/lineItems/items/commitmentDrawdowns` to the response with the `200` status - added the optional property `data/items/lineItems/items/creditCoverage` to the response with the `200` status - …3 more - **2025-12-03** `ac93d1a9e6d9`: 1 warning, 1 info - added the new `AD_HOC` enum value to the `data/items/lineItems/items/lineItemType` response property for the response status `200` - added the optional property `data/items/statementStale` to the response with the `200` status - **2025-08-01** `9f9e5f3dbde7`: 1 breaking, 3 info - the response's body type changed from no type to `object` for status `200` - added the new optional `query` request parameter `additional` - added the optional property `data` to the response with the `200` status - added the optional property `nextToken` to the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/m3ter-com/apis/m3ter-api/changes/organizations/:orgId/bills/billingperiod/:lastDateInBillingPeriod/:billingFrequency/get.md) --- [API](https://skmtc.dev/m3ter-com/apis/m3ter-api.md) - [All operations](https://skmtc.dev/m3ter-com/apis/m3ter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/m3ter-com/apis/m3ter-api/revisions/85c514abc692?raw)