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