openapi: 3.1.0
info:
  title: Billing API
  description: |-
    Public cloud services are based on the “pay as you go” model, which means that you only pay for what you use. Your monthly invoice is calculated at the end of each month and based on your hourly resource usage during the month.

    With Scaleway’s Billing API, you can manage the billing of your Scaleway cloud services.


    <Message type="note">
    You may also be interested in the [Account API](https://www.scaleway.com/en/developers/api/account/project-api/) to manage your Projects, and the [IAM API](https://www.scaleway.com/en/developers/api/iam/) to manage users, permissions and API keys in your Organization.
    </Message>


    ## Concepts and pricing

    Refer to our [Account concepts page](https://www.scaleway.com/en/docs/account/concepts/) to find more information on features like billing alerts, and our [dedicated pricing page](https://www.scaleway.com/en/pricing/?tags=available) for full details about the rates applied on each Scaleway product.




    ## Quickstart

    1. Configure your environment variables.

        <Message type="note">
        This is an optional step that seeks to simplify your usage of the API.
        </Message>

        ```bash
        export SCW_SECRET_KEY="<API secret key>"
        export SCW_ORGANIZATION_ID="<Scaleway Organization ID>"
        ```

    2. Run the following command to obtain your consumption over the current month.

        ```bash
        curl -X GET \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          "https://api.scaleway.com/billing/v2alpha1/consumption?organization_id=$SCW_ORGANIZATION_ID"
        ```

    3. Run the following command to list your invoices.

        ```bash
        curl -X GET \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          "https://api.scaleway.com/billing/v2alpha1/invoices"
        ```

        You should get an output similar to the following one, providing details about your invoices.

        <Message type="note">
        This is a response example, the UUIDs displayed are not real.
        </Message>

        ```bash
        {
          "total_count": "1",
          "invoices": [
            {
              "id": "66f588c7-91e9-5ce9-cedb-4733f791cf73",
              "start_date": "2022-03-22T12:34:56.123456Z",
              "issued_date": "2022-03-22T12:34:56.123456Z",
              "due_date": "2022-03-22T12:34:56.123456Z",
              "total_untaxed": {
                "currency_code": "EUR",
                "units": "9",
                "nanos": "360000000"
              },
              "total_taxed": {
                "currency_code": "EUR",
                "units": "9",
                "nanos": "360000000"
              },
              "invoice_type": "periodic",
              "number": "0"
            }
          ]
        }
        ```

    4. Run the following command to download an invoice based on its ID.

        Make sure to replace the example ID in the URL with the actual invoice ID you want to download.

        ```bash
        curl -X GET \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          "https://api.scaleway.com/billing/v2alpha1/invoices/66f588c7-91e9-5ce9-cedb-4733f791cf73/download"
        ```


    <Message type="requirement">
    - You have an account and are logged into the [Scaleway console](https://console.scaleway.com/organization)
    - You have created an [API key](https://www.scaleway.com/en/docs/iam/how-to/create-api-keys/) and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/iam/reference-content/permission-sets/) to perform the actions described on this page
    - You have [installed `curl`](https://curl.se/download.html)
    </Message>



    ## Technical limitations

    The following limitations apply to use of the Billing API:

    - You must have appropriate IAM permissions to manage billing. If you are the Owner of the Organization, you will automatically have these permissions. Otherwise, you will need a policy giving you the BillingManager permission set. If you were previously a Billing Administrator, you will automatically have been migrated to the BillingAdministrator group when you activated IAM, which gives you the appropriate permissions.
    - You only need BillingReadOnly permissions to query consumption.

    ## Going further

    For more help using Scaleway’s Billing API, check out the following resources:

    - Our [main documentation](https://www.scaleway.com/en/docs/account/)
    - Our [Slack Community](https://www.scaleway-community.slack.com/)
    - Our [support ticketing system](https://www.scaleway.com/en/docs/account/how-to/open-a-support-ticket/).
  version: v2alpha1
servers:
- url: https://api.scaleway.com
tags:
- name: Consumption
  description: |
    The consumption reflects the amount of money you have spent for the products you have used.
    The consumption value is monetary and is not computed in real time.
- name: Invoices
- name: Discounts
  description: |
    List all discounts for an organization and usable categories/products/offers/references/regions/zones where the discount can be applied.
components:
  schemas:
    scaleway.billing.v2alpha1.Discount:
      type: object
      properties:
        id:
          type: string
          description: The ID of the discount.
        creation_date:
          type: string
          description: The creation date of the discount. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        organization_id:
          type: string
          description: The organization ID of the discount.
        description:
          type: string
          description: The description of the discount.
        value:
          type: number
          description: The initial value of the discount.
          format: double
        value_used:
          type: number
          description: The value indicating how much of the discount has been used.
          format: double
        value_remaining:
          type: number
          description: The remaining value of the discount.
          format: double
        mode:
          type: string
          description: The mode of the discount.
          enum:
          - unknown_discount_mode
          - discount_mode_rate
          - discount_mode_value
          - discount_mode_splittable
          x-enum-descriptions:
            values:
              unknown_discount_mode: Unknown discount mode
              discount_mode_rate: A rate discount that reduces each customer bill
                by the discount value percentage
              discount_mode_value: A value discount that reduces the amount of the
                customer bill by the discount value
              discount_mode_splittable: A fixed sum to be deducted from the user's
                bills
          default: unknown_discount_mode
        start_date:
          type: string
          description: The start date of the discount. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        stop_date:
          type: string
          description: The stop date of the discount. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        coupon:
          type: object
          description: The description of the coupon.
          properties:
            description:
              type: string
              description: The description of the coupon.
              nullable: true
          x-properties-order:
          - description
        filters:
          type: array
          description: List of products/ranges/regions/zones to limit the usability
            of discounts.
          items:
            $ref: '#/components/schemas/scaleway.billing.v2alpha1.Discount.Filter'
      x-properties-order:
      - id
      - creation_date
      - organization_id
      - description
      - value
      - value_used
      - value_remaining
      - mode
      - start_date
      - stop_date
      - coupon
      - filters
    scaleway.billing.v2alpha1.Discount.Filter:
      type: object
      properties:
        type:
          type: string
          description: Type of the filter.
          enum:
          - unknown_type
          - product_category
          - product
          - product_offer
          - product_reference
          - region
          - zone
          x-enum-descriptions:
            values:
              unknown_type: Unknown filter type
              product_category: Product category, such as Compute, Network, Observability
              product: Products within the Product category. For example, VPC, Private
                Networks, and Public Gateways are products in the Network category
              product_offer: The offer of a product. For example, "VPC Public Gateway
                S", "VPC Public Gateway M" for the VPC product
              product_reference: Identifies the reference based on category, product,
                range, size, region, and zone. It can sometimes include different
                product options, such as licenses and monthly payments
              region: Region name like "FR-PAR", "NL-AMS", "PL-WAW"
              zone: Zone name like "FR-PAR-1", "FR-PAR-2", "FR-PAR-3"
          default: unknown_type
        value:
          type: string
          description: Value of filter, it can be a product/range/region/zone value.
        exclude:
          type: boolean
          description: Boolean to describe if filter is an excluding filter.
      x-properties-order:
      - type
      - value
      - exclude
    scaleway.billing.v2alpha1.GetConsumptionResponse:
      type: object
      properties:
        consumptions:
          type: array
          description: Detailed consumption list.
          items:
            $ref: '#/components/schemas/scaleway.billing.v2alpha1.GetConsumptionResponse.Consumption'
        updated_at:
          type: string
          description: Last consumption update date. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
      x-properties-order:
      - consumptions
      - updated_at
    scaleway.billing.v2alpha1.GetConsumptionResponse.Consumption:
      type: object
      properties:
        value:
          type: object
          description: Monetary value of the consumption.
          properties:
            currency_code:
              type: string
            units:
              type: integer
              format: int64
            nanos:
              type: integer
              format: int32
          x-properties-order:
          - currency_code
          - units
          - nanos
        description:
          type: string
          description: Description of the consumption.
        project_id:
          type: string
          description: Project ID of the consumption.
        category:
          type: string
          description: Category of the consumption.
        operation_path:
          type: string
          description: Unique identifier of the product.
      x-properties-order:
      - value
      - description
      - project_id
      - category
      - operation_path
    scaleway.billing.v2alpha1.Invoice:
      type: object
      properties:
        id:
          type: string
          description: Invoice ID.
        start_date:
          type: string
          description: Start date of the billing period. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        issued_date:
          type: string
          description: Date when the invoice was sent to the customer. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        due_date:
          type: string
          description: Payment time limit, set according to the Organization's payment
            conditions. (RFC 3339 format)
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
          nullable: true
        total_untaxed:
          type: object
          description: Total amount, untaxed.
          properties:
            currency_code:
              type: string
            units:
              type: integer
              format: int64
            nanos:
              type: integer
              format: int32
          x-properties-order:
          - currency_code
          - units
          - nanos
        total_taxed:
          type: object
          description: Total amount, taxed.
          properties:
            currency_code:
              type: string
            units:
              type: integer
              format: int64
            nanos:
              type: integer
              format: int32
          x-properties-order:
          - currency_code
          - units
          - nanos
        invoice_type:
          type: string
          description: Type of invoice.
          enum:
          - unknown_type
          - periodic
          - purchase
          default: unknown_type
        number:
          type: integer
          description: Invoice number.
          format: int32
      x-properties-order:
      - id
      - start_date
      - issued_date
      - due_date
      - total_untaxed
      - total_taxed
      - invoice_type
      - number
    scaleway.billing.v2alpha1.ListDiscountsResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total number of discounts.
          format: uint64
        discounts:
          type: array
          description: Paginated returned discounts.
          items:
            $ref: '#/components/schemas/scaleway.billing.v2alpha1.Discount'
      x-properties-order:
      - total_count
      - discounts
    scaleway.billing.v2alpha1.ListInvoicesResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total number of invoices.
          format: uint32
        invoices:
          type: array
          description: Paginated returned invoices.
          items:
            $ref: '#/components/schemas/scaleway.billing.v2alpha1.Invoice'
      x-properties-order:
      - total_count
      - invoices
    scaleway.std.File:
      type: object
      properties:
        name:
          type: string
        content_type:
          type: string
        content:
          type: string
      x-properties-order:
      - name
      - content_type
      - content
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey
paths:
  /billing/v2alpha1/consumption:
    get:
      tags:
      - Consumption
      operationId: GetConsumption
      summary: Get current month's consumption
      description: |-
        The consumption reflects the amount of money you have spent for the products you have used.
        The consumption value is monetary and is not computed in real time.
      parameters:
      - in: query
        name: organization_id
        description: Filter by organization ID. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.billing.v2alpha1.GetConsumptionResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/billing/v2alpha1/consumption?organization_id=6170692e-7363-616c-6577-61792e636f6d"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/billing/v2alpha1/consumption" \
            X-Auth-Token:$SCW_SECRET_KEY \
            organization_id==6170692e-7363-616c-6577-61792e636f6d
  /billing/v2alpha1/discounts:
    get:
      tags:
      - Discounts
      operationId: ListDiscounts
      summary: List all user's discounts
      description: List all discounts for an organization and usable categories/products/offers/references/regions/zones
        where the discount can be applied.
      parameters:
      - in: query
        name: order_by
        description: Order discounts in the response by their description.
        schema:
          type: string
          enum:
          - creation_date_desc
          - creation_date_asc
          - start_date_desc
          - start_date_asc
          - stop_date_desc
          - stop_date_asc
          x-enum-descriptions:
            values:
              creation_date_desc: Order discounts by creation date (descending chronological
                order)
              creation_date_asc: Order discounts by creation date (ascending chronological
                order)
              start_date_desc: Order discounts by start date (descending chronological
                order)
              start_date_asc: Order discounts by start date (ascending chronological
                order)
              stop_date_desc: Order discounts by stop date (descending chronological
                order)
              stop_date_asc: Order discounts by stop date (ascending chronological
                order)
          default: creation_date_desc
      - in: query
        name: page
        description: Positive integer to choose the page to return.
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: Positive integer lower or equal to 100 to select the number of
          items to return.
        schema:
          type: integer
          format: uint32
      - in: query
        name: organization_id
        description: ID of the organization. (UUID format)
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.billing.v2alpha1.ListDiscountsResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/billing/v2alpha1/discounts"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/billing/v2alpha1/discounts" \
            X-Auth-Token:$SCW_SECRET_KEY
  /billing/v2alpha1/invoices:
    get:
      tags:
      - Invoices
      operationId: ListInvoices
      summary: List invoices
      description: List all your invoices, filtering by `start_date` and `invoice_type`.
        Each invoice has its own ID.
      parameters:
      - in: query
        name: organization_id
        description: Organization ID to filter for, only invoices from this Organization
          will be returned. (UUID format)
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: started_after
        description: Invoice's `start_date` is greater or equal to `started_after`.
          (RFC 3339 format)
        schema:
          type: string
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
      - in: query
        name: started_before
        description: Invoice's `start_date` precedes `started_before`. (RFC 3339 format)
        schema:
          type: string
          format: date-time
          example: "2022-03-22T12:34:56.123456Z"
      - in: query
        name: invoice_type
        description: Invoice type. It can either be `periodic` or `purchase`.
        schema:
          type: string
          enum:
          - unknown_type
          - periodic
          - purchase
          default: unknown_type
      - in: query
        name: page
        description: Positive integer to choose the page to return.
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: Positive integer lower or equal to 100 to select the number of
          items to return.
        schema:
          type: integer
          format: uint32
      - in: query
        name: order_by
        description: How invoices are ordered in the response.
        schema:
          type: string
          enum:
          - invoice_number_desc
          - invoice_number_asc
          - start_date_desc
          - start_date_asc
          - issued_date_desc
          - issued_date_asc
          - due_date_desc
          - due_date_asc
          - total_untaxed_desc
          - total_untaxed_asc
          - total_taxed_desc
          - total_taxed_asc
          - invoice_type_desc
          - invoice_type_asc
          default: invoice_number_desc
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.billing.v2alpha1.ListInvoicesResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/billing/v2alpha1/invoices"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/billing/v2alpha1/invoices" \
            X-Auth-Token:$SCW_SECRET_KEY
  /billing/v2alpha1/invoices/{invoice_id}/download:
    get:
      tags:
      - Invoices
      operationId: DownloadInvoice
      summary: Download an invoice
      description: Download a specific invoice, specified by its ID.
      parameters:
      - in: path
        name: invoice_id
        description: Invoice ID. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: file_type
        description: Wanted file type.
        schema:
          type: string
          enum:
          - pdf
          default: pdf
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.std.File'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/billing/v2alpha1/invoices/{invoice_id}/download"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/billing/v2alpha1/invoices/{invoice_id}/download" \
            X-Auth-Token:$SCW_SECRET_KEY