Soracom Billing API
Retrieve usage charges (monthly bills, daily bill items, per-SIM and per-bill-item summaries), export bills to CSV, manage payment methods, register coupons, manage orders, and configure shipping addresses.
OpenAPI Specification
openapi: 3.0.0
info:
title: Soracom and Query Analysis Billing API
description: Run SQL queries against Soracom Query, fetch query schemas, and search SIMs, Inventory devices, and Sigfox devices.
version: 20250903-043502
servers:
- description: Japan coverage production API endpoint
url: https://api.soracom.io/v1
- description: Global coverage production API endpoint
url: https://g.api.soracom.io/v1
tags:
- description: '[Usage charges (billing details)](/en/guides/accounting/check-usage/)'
name: Billing
paths:
/bills:
get:
description: 'Gets a list of finalized past billing history.
**Warning**: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact [Soracom Support](https://support.soracom.io).
'
operationId: getBillingHistory
responses:
'200':
content:
application/json:
example:
billList:
- amount: 28734
paymentStatus: paid
paymentTransactionId: 12345678901234567_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
state: closed
yearMonth: '202208'
- amount: 27075
paymentStatus: paid
paymentTransactionId: 12345678901234567_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
state: closed
yearMonth: '202207'
schema:
$ref: '#/components/schemas/GetBillingHistoryResponse'
description: A list of finalized past billing history.
security:
- api_key: []
api_token: []
summary: Gets a list of finalized past billing history
tags:
- Billing
x-soracom-cli:
- bills list
/bills/{yyyyMM}:
get:
description: 'Gets a finalized past billing history for the specified month. If you specify current month (the month in which the usage fee has not yet been finalized), you will get the preliminary value.
**Warning**: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact [Soracom Support](https://support.soracom.io).
'
operationId: getBilling
parameters:
- description: Target year and month
in: path
name: yyyyMM
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
amount: 28734
currency: JPY
paymentStatus: paid
paymentTransactionId: 12345678901234567_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
state: closed
yearMonth: '202208'
schema:
$ref: '#/components/schemas/MonthlyBill'
description: The billing history for the specified month.
'404':
description: '- The billing history for the specified month has not been finalized.
- There is no charge for the specified month.
'
security:
- api_key: []
api_token: []
summary: Gets a finalized past billing history for the specified month
tags:
- Billing
x-soracom-cli:
- bills get
/bills/{yyyyMM}/daily:
get:
description: 'Gets a daily bill for the specified month. Fees charged on a monthly basis cannot be retrieved. If you specify current month (a month for which the fee has not yet been finalized), a preliminary value will be returned.
**Warning**: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact [Soracom Support](https://support.soracom.io).
'
operationId: getBillingPerDay
parameters:
- description: Target year and month
in: path
name: yyyyMM
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
billList:
- amount: 285
currency: JPY
date: '20220902'
- amount: 580
currency: JPY
date: '20220901'
schema:
$ref: '#/components/schemas/DailyBillResponse'
description: Daily billing information for the specified month.
'404':
description: Bill not found.
security:
- api_key: []
api_token: []
summary: Get a daily bill
tags:
- Billing
x-soracom-cli:
- bills get-daily
/bills/{yyyyMM}/export:
post:
description: 'Export historical [Detailed billing CSV](/en/docs/account/billing/#detailed-billing-csv) to dedicated storage and issue URL to download.
**Warning**: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact [Soracom Support](https://support.soracom.io).
'
operationId: exportBilling
parameters:
- description: Target year and month
in: path
name: yyyyMM
required: true
schema:
type: string
- description: 'Specify how to get the URL to download the billing details CSV.
- `async`: Get the `exportedFieldId` without waiting for the URL to be issued on the Soracom platform. Specify this `exportedFieldId` in [Files:getExportedFile API](#!/Files/getExportedFile) to get the URL. If the file size of the billing details CSV is huge, use `async`.
- `sync` (default): Wait for the URL to be issued on the Soracom platform. However, if the file size of the billing details CSV is huge, it may time out and the URL cannot be retrieved. If the timeout occurs, specify `async`.
'
in: query
name: export_mode
required: false
schema:
enum:
- async
- sync
type: string
responses:
'200':
content:
application/json:
examples:
(1) export_mode=async:
value:
exportedFileId: fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
exportedFilePath: //files/exported/fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
(2) export_mode=sync:
value:
url: https://soracom-xxxxxxxx-....
schema:
$ref: '#/components/schemas/FileExportResponse'
description: Export process successfully initiated. Contains the download URL or export ID.
'404':
description: Bill not found.
security:
- api_key: []
api_token: []
summary: Export historical Detailed billing CSV to dedicated storage
tags:
- Billing
x-soracom-cli:
- bills export
/bills/latest:
get:
description: Retrieves the preliminary usage fee for the current month (the month in which the usage fee has not yet been finalized).
operationId: getLatestBilling
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetLatestBill'
description: The latest billing information for the current month.
security:
- api_key: []
api_token: []
summary: Get latest bill
tags:
- Billing
x-soracom-cli:
- bills get-latest
/bills/latest/export:
post:
description: Export [Detailed Billing CSV](/en/docs/account/billing/#detailed-billing-csv) for current month (the month in which the usage fee has not yet been finalized) to dedicated storage and issue a URL to download it. The fees will be finalized by the second business day of the following month. The Detailed billing CSV exported using this API will output preliminary values.
operationId: exportLatestBilling
parameters:
- description: 'Specify how to get the URL to download the billing details CSV.
- `async`: Get the `exportedFieldId` without waiting for the URL to be issued on the Soracom platform. Specify this `exportedFieldId` in [Files:getExportedFile API](#!/Files/getExportedFile) to get the URL. If the file size of the billing details CSV is huge, use `async`.
- `sync` (default): Wait for the URL to be issued on the Soracom platform. However, if the file size of the billing details CSV is huge, it may time out and the URL cannot be retrieved. If the timeout occurs, specify `async`.
'
in: query
name: export_mode
required: false
schema:
enum:
- async
- sync
type: string
responses:
'200':
content:
application/json:
examples:
(1) export_mode=async:
value:
exportedFileId: fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
exportedFilePath: //files/exported/fe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
(2) export_mode=sync:
value:
url: https://soracom-xxxxxxxx-....
schema:
$ref: '#/components/schemas/FileExportResponse'
description: Export process successfully initiated. Contains the download URL or export ID.
security:
- api_key: []
api_token: []
summary: Export latest billing CSV file to S3
tags:
- Billing
x-soracom-cli:
- bills export-latest
/bills/summaries/bill_items:
get:
description: 'Get a billing summary of bill items for the last 4 months (this month to 3 months ago). Sorted by date from newest to oldest.
The summary you can get from this API is equivalent to the usage fees displayed in the [COSTS BY SERVICE] panel of the Billing Dashboard. For more information, please refer to [Billing Information](/en/docs/account/billing/).
'
operationId: getBillingSummaryOfBillItems
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/BillingSummaryResponseOfBillItems'
type: array
description: A billing summary of bill items for the last 4 months.
security:
- api_key: []
api_token: []
summary: Gets a billing summary of bill items.
tags:
- Billing
x-soracom-cli:
- bills summaries get-bill-items
/bills/summaries/sims:
get:
description: 'Get a billing summary of SIMs for the last 4 months (current month to 3 months ago). Sorted by date from newest to oldest.
The summary you get from this API is equivalent to the rates displayed in the [COSTS PER SIM (TOP 100)] panel of the Rates Dashboard. For more information, please refer to [Billing Information](/en/docs/account/billing/).
'
operationId: getBillingSummaryOfSims
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/BillingSummaryResponseOfSims'
type: array
description: A billing summary of SIMs for the last 4 months.
security:
- api_key: []
api_token: []
summary: Gets a billing summary of SIMs
tags:
- Billing
x-soracom-cli:
- bills summaries get-sims
components:
schemas:
GetLatestBill:
properties:
amount:
description: Amount of bills.
format: double
type: number
currency:
description: Currency of bills.
enum:
- JPY
- USD
- EUR
type: string
lastEvaluatedTime:
description: Date and time when calculated.
example: yyyyMMddHHmmss
type: string
type: object
BillItemCostBreakdown:
properties:
amount:
description: Amount.
format: double
type: number
billItemCategory:
description: Bill item category.
type: string
billItemName:
description: Bill item name.
type: string
MonthlyBill:
properties:
amount:
description: Amount of monthly bills.
format: double
type: number
appliedCouponAmount:
description: Amount of coupon applied.
format: double
type: number
currency:
description: Currency of bills.
enum:
- JPY
- USD
- EUR
type: string
paymentStatus:
description: 'Latest payment status. For details, please refer to [Payment status of usage charges](https://support.soracom.io/hc/en-us/articles/360029337031).
- `lessThanMinimumCharge`: Will be billed in the next month or later. (due to less than minimum charge)
- `paying`: Payment in progress
- `paid`: Paid
- `fail`: Process failed
- `refunding`: Refund in progress
- `refunded`: Refunded
- `refund_fail`: Refund failed
- `delegating_to_third_party`: Delegating receivables
- `delegated_to_third_party`: Delegated
- `charging`: Charging in progress
- `canceling`: Canceling
- `cancelled`: Cancelled
- `cancel_failed`: Failed to cancel
'
enum:
- lessThanMinimumCharge
- paying
- paid
- fail
- refunding
- refunded
- refund_fail
- delegating_to_third_party
- delegated_to_third_party
- charging
- canceling
- cancelled
- cancel_failed
type: string
paymentTransactionId:
description: Transaction ID. Call [Payment:getPaymentTransaction API](#!/Payment/getPaymentTransaction) with this ID to get detail of payment.
type: string
state:
description: 'Aggregation status of the billing
- `temporary`: Aggregating
- `closed`: Confirmed
'
enum:
- temporary
- closed
type: string
yearMonth:
description: Year and month.
format: yyyyMM
type: string
type: object
DailyBillResponse:
properties:
billList:
description: List of daily bills.
items:
$ref: '#/components/schemas/DailyBill'
type: array
type: object
BillingSummaryResponseOfSims:
properties:
costBreakdownList:
description: List of cost breakdown. The list is sorted by amount in descending order, and include up to 100 items.
items:
$ref: '#/components/schemas/SimCostBreakdown'
type: array
currency:
description: Currency of bills.
enum:
- JPY
- USD
- EUR
type: string
updatedTime:
description: Last updated time in UNIX time in seconds.
format: int64
type: integer
yearMonth:
description: Year and month.
type: string
type: object
SimCostBreakdown:
properties:
amount:
description: Amount.
format: double
type: number
simId:
description: SIM ID.
type: string
DailyBill:
properties:
amount:
description: Amount of bills.
format: double
type: number
currency:
description: Currency of bills.
enum:
- JPY
- USD
- EUR
type: string
date:
description: Date
format: yyyyMMdd
type: string
type: object
BillingSummaryResponseOfBillItems:
properties:
costBreakdownList:
description: List of cost breakdown. The list is sorted by amount in descending order.
items:
$ref: '#/components/schemas/BillItemCostBreakdown'
type: array
currency:
description: Currency of bills.
enum:
- JPY
- USD
- EUR
type: string
updatedTime:
description: Last updated time in UNIX time in seconds.
format: int64
type: integer
yearMonth:
description: Year and month.
type: string
type: object
GetBillingHistoryResponse:
properties:
billList:
description: List of monthly bills.
items:
$ref: '#/components/schemas/MonthlyBill'
type: array
type: object
FileExportResponse:
properties:
exportedFileId:
description: File Export ID. Specify this ID when calling [Files:getExportedFile API](#!/Files/getExportedFile) to get the URL to download the file. Included only if `export_mode` is `async`.
type: string
exportedFilePath:
description: Path of the exported file. Included only if `export_mode` is `async`.
type: string
url:
description: URL to download the file. Included only if `export_mode` is `sync`.
type: string
type: object
securitySchemes:
api_key:
description: 'API key for authentication. Obtain this from the Soracom User Console or via the Auth API.
Required in combination with an API token for all authenticated requests.
'
in: header
name: X-Soracom-API-Key
type: apiKey
api_token:
description: 'API token for authentication. This token has an expiration time and must be refreshed periodically.
Required in combination with an API key for all authenticated requests.'
in: header
name: X-Soracom-Token
type: apiKey