Return All Invoices for One Organization

GET /api/atlas/v2/orgs/{orgId}/invoices

Returns all invoices that MongoDB issued to the specified organization. This list includes all invoices regardless of invoice status. To use this resource, the requesting Service Account or API Key must have the Organization Billing Viewer, Organization Billing Admin, or Organization Owner role. If you have a cross-organization setup, you can view linked invoices if you have the Organization Billing Admin or Organization Owner role. To compute the total owed amount of the invoices - sum up total owed of each invoice. It could be computed as a sum of owed amount of each payment included into the invoice. To compute payment's owed amount - use formula totalBilledCents * unitPrice + salesTax - startingBalanceCents.

Path parameters

  • orgId string Required

    Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the /orgs endpoint to retrieve all organizations to which the authenticated user has access.

    Format should match the following pattern: ^([a-f0-9]{24})$.

Query parameters

  • envelope boolean

    Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

    Default value is false.

  • includeCount boolean

    Flag that indicates whether the response returns the total number of items (totalCount) in the response.

    Default value is true.

  • itemsPerPage integer

    Number of items that the response returns per page.

    Minimum value is 1, maximum value is 500. Default value is 100.

  • pageNum integer

    Number of the page that displays the current set of the total objects that the response returns.

    Minimum value is 1. Default value is 1.

  • pretty boolean

    Flag that indicates whether the response body should be in the prettyprint format.

    Default value is false.

    Prettyprint
  • viewLinkedInvoices boolean

    Flag that indicates whether to return linked invoices in the linkedInvoices field.

    Default value is true.

  • statusNames array[string]

    Statuses of the invoice to be retrieved. Omit to return invoices of all statuses.

    Values are PENDING, CLOSED, FORGIVEN, FAILED, PAID, FREE, PREPAID, or INVOICED.

  • fromDate string(date)

    Retrieve the invoices the startDates of which are greater than or equal to the fromDate. If omit, the invoices return will go back to earliest startDate.

  • toDate string(date)

    Retrieve the invoices the endDates of which are smaller than or equal to the toDate. If omit, the invoices return will go further to latest endDate.

  • sortBy string

    Field used to sort the returned invoices by. Use in combination with orderBy parameter to control the order of the result.

    Values are START_DATE or END_DATE. Default value is END_DATE.

  • orderBy string

    Field used to order the returned invoices by. Use in combination of sortBy parameter to control the order of the result.

    Values are desc or asc. Default value is desc.

Responses

  • 200 application/vnd.atlas.2023-01-01+json

    OK

    Hide response attributes Show response attributes object
    • results array[object]

      List of returned documents that MongoDB Cloud provides when completing this request.

      Hide results attributes Show results attributes object
      • amountBilledCents integer(int64)

        Sum of services that the specified organization consumed in the period covered in this invoice. This parameter expresses its value in cents (100ths of one US Dollar).

      • amountPaidCents integer(int64)

        Sum that the specified organization paid toward this invoice. This parameter expresses its value in cents (100ths of one US Dollar).

      • created string(date-time)

        Date and time when MongoDB Cloud created this invoice. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

      • creditsCents integer(int64)

        Sum that MongoDB credited the specified organization toward this invoice. This parameter expresses its value in cents (100ths of one US Dollar).

      • endDate string(date-time)

        Date and time when MongoDB Cloud finished the billing period that this invoice covers. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

      • id string

        Unique 24-hexadecimal digit string that identifies the invoice submitted to the specified organization. Charges typically post the next day.

        Format should match the following pattern: ^([a-f0-9]{24})$.

      • linkedInvoices array[object]

        List that contains the invoices for organizations linked to the paying organization.

      • orgId string

        Unique 24-hexadecimal digit string that identifies the organization charged for services consumed from MongoDB Cloud.

        Format should match the following pattern: ^([a-f0-9]{24})$.

      • salesTaxCents integer(int64)

        Sum of sales tax applied to this invoice. This parameter expresses its value in cents (100ths of one US Dollar).

      • startDate string(date-time)

        Date and time when MongoDB Cloud began the billing period that this invoice covers. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

      • startingBalanceCents integer(int64)

        Sum that the specified organization owed to MongoDB when MongoDB issued this invoice. This parameter expresses its value in US Dollars.

      • statusName string

        Phase of payment processing in which this invoice exists when you made this request. Accepted phases include:

        • CLOSED: MongoDB finalized all charges in the billing cycle but has yet to charge the customer.
        • FAILED: MongoDB attempted to charge the provided credit card but charge for that amount failed.
        • FORGIVEN: Customer initiated payment which MongoDB later forgave.
        • FREE: All charges totalled zero so the customer won't be charged.
        • INVOICED: MongoDB handled these charges using elastic invoicing.
        • PAID: MongoDB succeeded in charging the provided credit card.
        • PENDING: Invoice includes charges for the current billing cycle.
        • PREPAID: Customer has a pre-paid plan so they won't be charged.

        Values are PENDING, CLOSED, FORGIVEN, FAILED, PAID, FREE, PREPAID, or INVOICED.

      • subtotalCents integer(int64)

        Sum of all positive invoice line items contained in this invoice. This parameter expresses its value in cents (100ths of one US Dollar).

      • updated string(date-time)

        Date and time when MongoDB Cloud last updated the value of this payment. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

    • totalCount integer(int32)

      Total number of documents available. MongoDB Cloud omits this value if includeCount is set to false. The total number is an estimate and may not be exact.

      Minimum value is 0.

  • 401 application/json

    Unauthorized.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Bad request detail.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Describes all violations in a client request.

        Hide fields attributes Show fields attributes object
        • description string Required

          A description of why the request element is bad.

        • field string Required

          A path that leads to a field in the request body.

    • detail string

      Describes the specific conditions or reasons that cause each type of error.

    • error integer(int32) Required

      HTTP status code returned with this error.

      External documentation
    • errorCode string Required

      Application error code returned with this error.

    • parameters array[object]

      Parameters used to give more information about the error.

    • reason string

      Application error message returned with this error.

  • 403 application/json

    Forbidden.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Bad request detail.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Describes all violations in a client request.

        Hide fields attributes Show fields attributes object
        • description string Required

          A description of why the request element is bad.

        • field string Required

          A path that leads to a field in the request body.

    • detail string

      Describes the specific conditions or reasons that cause each type of error.

    • error integer(int32) Required

      HTTP status code returned with this error.

      External documentation
    • errorCode string Required

      Application error code returned with this error.

    • parameters array[object]

      Parameters used to give more information about the error.

    • reason string

      Application error message returned with this error.

  • 404 application/json

    Not Found.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Bad request detail.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Describes all violations in a client request.

        Hide fields attributes Show fields attributes object
        • description string Required

          A description of why the request element is bad.

        • field string Required

          A path that leads to a field in the request body.

    • detail string

      Describes the specific conditions or reasons that cause each type of error.

    • error integer(int32) Required

      HTTP status code returned with this error.

      External documentation
    • errorCode string Required

      Application error code returned with this error.

    • parameters array[object]

      Parameters used to give more information about the error.

    • reason string

      Application error message returned with this error.

  • 500 application/json

    Internal Server Error.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Bad request detail.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Describes all violations in a client request.

        Hide fields attributes Show fields attributes object
        • description string Required

          A description of why the request element is bad.

        • field string Required

          A path that leads to a field in the request body.

    • detail string

      Describes the specific conditions or reasons that cause each type of error.

    • error integer(int32) Required

      HTTP status code returned with this error.

      External documentation
    • errorCode string Required

      Application error code returned with this error.

    • parameters array[object]

      Parameters used to give more information about the error.

    • reason string

      Application error message returned with this error.

GET /api/atlas/v2/orgs/{orgId}/invoices
atlas api listInvoices --help
import (
	"os"
	"context"
	"log"
	sdk "go.mongodb.org/atlas-sdk/v20250312001/admin"
)

func main() {
	ctx := context.Background()
	clientID := os.Getenv("MONGODB_ATLAS_CLIENT_ID")
	clientSecret := os.Getenv("MONGODB_ATLAS_CLIENT_SECRET")

	client, err := sdk.NewClient(
		sdk.UseOAuthAuth(clientID, clientSecret),
		sdk.UseBaseURL(url))

	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	params = &sdk.ListInvoicesApiParams{}
	sdkResp, httpResp, err := client.InvoicesApi.
		ListInvoicesWithParams(ctx, params).
		Execute()
}
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/vnd.atlas.2025-03-12+json" \
  -X GET "https://cloud.mongodb.com/api/atlas/v2/orgs/{orgId}/invoices?pretty=true"
curl --user "${PUBLIC_KEY}:${PRIVATE_KEY}" \
  --digest \
  --header "Accept: application/vnd.atlas.2025-03-12+json" \
  -X GET "https://cloud.mongodb.com/api/atlas/v2/orgs/{orgId}/invoices?pretty=true"
Response examples (200)
{
  "links": [
    {
      "href": "https://cloud.mongodb.com/api/atlas",
      "rel": "self"
    }
  ],
  "results": [
    {
      "amountBilledCents": 42,
      "amountPaidCents": 42,
      "created": "2025-05-04T09:42:00Z",
      "creditsCents": 42,
      "endDate": "2025-05-04T09:42:00Z",
      "id": "32b6e34b3d91647abb20e7b8",
      "linkedInvoices": [
        {}
      ],
      "links": [
        {
          "href": "https://cloud.mongodb.com/api/atlas",
          "rel": "self"
        }
      ],
      "orgId": "32b6e34b3d91647abb20e7b8",
      "salesTaxCents": 42,
      "startDate": "2025-05-04T09:42:00Z",
      "startingBalanceCents": 42,
      "statusName": "PENDING",
      "subtotalCents": 42,
      "updated": "2025-05-04T09:42:00Z"
    }
  ],
  "totalCount": 42
}
Response examples (401)
{
  "error": 401,
  "detail": "(This is just an example, the exception may not be related to this endpoint)",
  "reason": "Unauthorized",
  "errorCode": "NOT_ORG_GROUP_CREATOR"
}
Response examples (403)
{
  "error": 403,
  "detail": "(This is just an example, the exception may not be related to this endpoint)",
  "reason": "Forbidden",
  "errorCode": "CANNOT_CHANGE_GROUP_NAME"
}
Response examples (404)
{
  "error": 404,
  "detail": "(This is just an example, the exception may not be related to this endpoint) Cannot find resource AWS",
  "reason": "Not Found",
  "errorCode": "RESOURCE_NOT_FOUND"
}
Response examples (500)
{
  "error": 500,
  "detail": "(This is just an example, the exception may not be related to this endpoint)",
  "reason": "Internal Server Error",
  "errorCode": "UNEXPECTED_ERROR"
}