openapi: 3.0.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.\n\nWith
Scaleway’s Billing API, you can manage the billing of your Scaleway cloud services.\n\n(switchcolumn)\n\nYou may also be interested in the [Account API](https://www.scaleway.com/en/developers/api/account/)
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.\n\n(switchcolumn)\n\n##
Concepts and pricing\n\nRefer to our [Account concepts page](https://www.scaleway.com/en/docs/console/my-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.\n\n(switchcolumn)\n(switchcolumn)\n\n##
Quickstart\n\n1. Configure your environment variables.\n\n \n
\ This is an optional step that seeks to simplify your usage of the API.\n \n\n
\ ```bash\n export SCW_SECRET_KEY=\"\" \n export SCW_ORGANIZATION_ID=\"\"\n ```\n\n2. Run the following command to obtain your consumption
over the current month.\n\n ```bash\n curl -X GET \\\n -H \"X-Auth-Token:
$SCW_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n \"https://api.scaleway.com/billing/v2alpha1/consumption?organization_id=$SCW_ORGANIZATION_ID\"\n
\ ```\n\n3. Run the following command to list your invoices.\n\n ```bash\n
\ curl -X GET \\\n -H \"X-Auth-Token: $SCW_SECRET_KEY\" \\\n -H \"Content-Type:
application/json\" \\\n \"https://api.scaleway.com/billing/v2alpha1/invoices\"\n
\ ```\n\n You should get an output similar to the following one, providing
details about your invoices.\n\n \n This is a response
example, the UUIDs displayed are not real.\n \n\n ```bash\n {\n
\ \"total_count\": \"1\",\n \"invoices\": [\n {\n \"id\":
\"66f588c7-91e9-5ce9-cedb-4733f791cf73\",\n \"start_date\": \"2022-03-22T12:34:56.123456Z\",\n
\ \"issued_date\": \"2022-03-22T12:34:56.123456Z\",\n \"due_date\":
\"2022-03-22T12:34:56.123456Z\",\n \"total_untaxed\": {\n \"currency_code\":
\"EUR\",\n \"units\": \"9\",\n \"nanos\": \"360000000\"\n
\ },\n \"total_taxed\": {\n \"currency_code\": \"EUR\",\n
\ \"units\": \"9\",\n \"nanos\": \"360000000\"\n },\n
\ \"invoice_type\": \"periodic\",\n \"number\": \"0\"\n }\n
\ ]\n }\n ```\n\n4. Run the following command to download an invoice
based on its ID.\n\n Make sure to replace the example ID in the URL with the
actual invoice ID you want to download.\n\n ```bash\n curl -X GET \\\n -H
\"X-Auth-Token: $SCW_SECRET_KEY\" \\\n -H \"Content-Type: application/json\"
\\\n \"https://api.scaleway.com/billing/v2alpha1/invoices/66f588c7-91e9-5ce9-cedb-4733f791cf73/download\"\n
\ ```\n\n(switchcolumn)\n\n- You have an account
and are logged into the [Scaleway console](https://console.scaleway.com/organization)\n-
You have created an [API key](https://www.scaleway.com/en/docs/identity-and-access-management/iam/how-to/create-api-keys/)
and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/identity-and-access-management/iam/reference-content/permission-sets/)
to perform the actions described on this page\n- You have [installed `curl`](https://curl.se/download.html)\n\n(switchcolumn)\n\n\n##
Technical limitations\n\nThe following limitations apply to use of the Billing
API:\n\n- 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.\n- You only need BillingReadOnly permissions
to query consumption.\n\n## Going further\n\nFor more help using Scaleway’s Billing
API, check out the following resources:\n\n- Our [main documentation](https://www.scaleway.com/en/docs/console/my-account/)\n-
Our [Slack Community](https://www.scaleway-community.slack.com/)\n- Our [support
ticketing system](https://www.scaleway.com/en/docs/console/my-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.
x-properties-order:
- type
- value
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
description: Filter by organization ID. (UUID format)
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
description: Order discounts in the response by their description.
enum:
- creation_date_desc
- creation_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)
default: creation_date_desc
- in: query
name: page
description: Positive integer to choose the page to return.
schema:
type: integer
description: Positive integer to choose the page to return.
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
description: Positive integer lower or equal to 100 to select the number
of items to return.
format: uint32
default: "100"
- in: query
name: organization_id
description: ID of the organization. (UUID format)
schema:
type: string
description: ID of the organization. (UUID format)
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
description: Organization ID to filter for, only invoices from this Organization
will be returned. (UUID format)
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
description: Invoice's `start_date` is greater or equal to `started_after`.
(RFC 3339 format)
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
description: Invoice's `start_date` precedes `started_before`. (RFC 3339
format)
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
description: Invoice type. It can either be `periodic` or `purchase`.
enum:
- unknown_type
- periodic
- purchase
default: unknown_type
- in: query
name: page
description: Positive integer to choose the page to return.
schema:
type: integer
description: Positive integer to choose the page to return.
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
description: Positive integer lower or equal to 100 to select the number
of items to return.
format: uint32
default: "20"
- in: query
name: order_by
description: How invoices are ordered in the response.
schema:
type: string
description: How invoices are ordered in the response.
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
description: Invoice ID. (UUID format)
example: 6170692e-7363-616c-6577-61792e636f6d
- in: query
name: file_type
description: Wanted file type.
schema:
type: string
description: Wanted file type.
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