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 Billing API
description: Retrieve usage charges, daily bill items, summaries, payment methods, coupons, orders, and shipping addresses.
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
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
/coupons:
get:
description: Returns a list of currently registered coupons.
operationId: listCoupons
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListCouponResponse'
description: OK.
security:
- api_key: []
api_token: []
summary: List coupons.
tags:
- Payment
x-soracom-cli:
- coupons list
post:
description: Creates a new coupon quotation. If the orderId is put in /coupons/{order_id}/confirm, the order is complete.
operationId: createCouponQuotation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEstimatedCouponRequest'
description: Coupon details.
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/EstimatedCouponModel'
description: Created.
security:
- api_key: []
api_token: []
summary: Create coupon quotation
tags:
- Order
x-soracom-cli:
- coupons create
/coupons/{coupon_code}/register:
post:
description: Registers a coupon.
operationId: registerCoupon
parameters:
- description: Coupon code.
in: path
name: coupon_code
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CouponResponse'
description: OK.
'400':
description: The coupon code is invalid or the coupon code registration limit has been reached.
security:
- api_key: []
api_token: []
summary: Register Coupon
tags:
- Payment
x-soracom-cli:
- coupons register
/payment_history/transactions/{payment_transaction_id}:
get:
description: 'Returns result of a payment transaction.
**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: getPaymentTransaction
parameters:
- description: Payment transaction ID. It can be obtained via [Billing:getBillingHistory API](#!/Billing/getBillingHistory)
or [Billing:getBilling API](#!/Billing/getBilling).
in: path
name: payment_transaction_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetPaymentTransactionResult'
description: OK.
'400':
description: Invalid payment transaction ID.
'404':
description: Payment transaction result not found.
security:
- api_key: []
api_token: []
summary: Get payment transaction result.
tags:
- Payment
x-soracom-cli:
- payment-history get
/payment_methods/current:
get:
description: Returns current payment methods. Detailed information is included in the properties.
operationId: getPaymentMethod
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetPaymentMethodResult'
description: OK.
'404':
description: Payment method not found.
security:
- api_key: []
api_token: []
summary: Get current payment method information.
tags:
- Payment
x-soracom-cli:
- payment-methods get-current
/payment_methods/current/activate:
post:
description: Activates a current payment method that has an error.
operationId: activatePaymentMethod
responses:
'200':
content:
application/json:
schema:
type: object
description: OK.
'404':
description: Payment method not found.
security:
- api_key: []
api_token: []
summary: Activate current payment method
tags:
- Payment
x-soracom-cli:
- payment-methods reactivate-current
/payment_statements:
get:
description: 'List payment statements.
**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: listPaymentStatements
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListPaymentStatementResponse'
description: OK.
security:
- api_key: []
api_token: []
summary: List payment statements
tags:
- Payment
x-soracom-cli:
- payment-statements list
/payment_statements/{payment_statement_id}/export:
post:
description: 'Export payment statement.
**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: exportPaymentStatement
parameters:
- description: Payment statement ID
in: path
name: payment_statement_id
required: true
schema:
type: string
- description: Export mode (async, sync)
in: query
name: export_mode
required: false
schema:
enum:
- async
- sync
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/FileExportResponse'
description: OK.
'400':
description: Invalid payment statement ID.
security:
- api_key: []
api_token: []
summary: Export payment statement
tags:
- Payment
x-soracom-cli:
- payment-statements export
/payment_statements/payer_information:
get:
description: Export payer information.
operationId: getPayerInformation
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterPayerInformationModel'
description: OK.
'400':
description: Payer information not found.
security:
- api_key: []
api_token: []
summary: Export payer information
tags:
- Payment
x-soracom-cli:
- payer-information get
post:
description: Register payer information.
operationId: registerPayerInformation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterPayerInformationModel'
description: Payer information to be registered in the accounting specification.
required: true
responses:
'201':
description: Created.
'400':
description: Invalid payer information.
security:
- api_key: []
api_token: []
summary: Register payer information
tags:
- Payment
x-soracom-cli:
- payer-information register
/volume_discounts:
get:
description: 'Returns a list of contracted long term discounts.
**Warning**: Information can be obtained up to 18 months in the past or 6 months after the contract ends. If you need
the information before that time, please contact [Soracom Support](https://support.soracom.io).
'
operationId: listVolumeDiscounts
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListVolumeDiscountResponse'
description: OK.
security:
- api_key: []
api_token: []
summary: List long term discounts
tags:
- Payment
x-soracom-cli:
- volume-discounts list
post:
description: Creates a new long term discount quotation. If the orderId is put in /volume_discounts/{order_id}/confirm,
the order is complete (Currently, long term discount is only applied to plan-D (without bundle), plan-K).
operationId: createVolumeDiscountQuotation
requestBody:
content:
application/json:
example:
contractTermMonth: 12
quantity: 1
startDate: '20220401'
volumeDiscountPaymentType: MONTHLY
volumeDiscountType: SORACOM_AIR_BASIC_CHARGE_V2
schema:
$ref: '#/components/schemas/CreateEstimatedVolumeDiscountRequest'
description: Long term discount contract details.
required: true
responses:
'201':
content:
application/json:
example:
currency: JPY
orderId: xxxxxxxxxxxxxx_xxxxxxxx
taxAmount: 0
totalAmount: 0
volumeDiscount:
contractTermMonth: 12
endDate: '20230331'
initialCost: 0
quantity: 1
startDate: '20220401'
taxIncludedInitialCost: 0
taxIncludedUnitPrice: 302.5
unitPrice: 275
volumeDiscountPaymentType: MONTHLY
volumeDiscountType: SORACOM_AIR_BASIC_CHARGE_V2
schema:
$ref: '#/components/schemas/EstimatedVolumeDiscountModel'
description: Created.
security:
- api_key: []
api_token: []
summary: Create long term discount quotation
tags:
- Order
x-soracom-cli:
- volume-discounts create
/volume_discounts/{contract_id}:
get:
description: 'Returns contracted long term discount.
**Warning**: Information can be obtained up to 18 months in the past or 6 months after the contract ends. If you need
the information before that time, please contact [Soracom Support](https://support.soracom.io).
'
operationId: getVolumeDiscount
parameters:
- description: Contract ID.
in: path
name: contract_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetVolumeDiscountResponse'
description: OK.
'400':
description: Long term discount not found.
security:
- api_key: []
api_token: []
summary: Get long term discount
tags:
- Payment
x-soracom-cli:
- volume-discounts get
/coupons/{order_id}/confirm:
put:
description: Performs a credit limit and confirms the order if no problems are encountered.
operationId: confirmCouponOrder
parameters:
- description: Order ID. You can get it by calling [Order:createCouponQuotation API](#/Order/createCouponQuotation).
in: path
name: order_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CouponResponse'
description: The confirmed coupon order.
security:
- api_key: []
api_token: []
summary: Confirm coupon order
tags:
- Order
x-soracom-cli:
- coupons confirm
/orders:
get:
description: 'Get a list of confirmed order 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: listOrders
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListOrderResponse'
description: A list of confirmed order history.
security:
- api_key: []
api_token: []
summary: Get a list of confirmed order history
tags:
- Order
x-soracom-cli:
- orders list
post:
description: Creates a new order quotation. If the orderId is put in /orders/{order_id}/confirm, the order is complete.
operationId: createQuotation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEstimatedOrderRequest'
description: Order item list and shipping address ID.
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/EstimatedOrderModel'
description: A new order quotation was created.
security:
- api_key: []
api_token: []
summary: Create Quotation
tags:
- Order
x-soracom-cli:
- orders create
/orders/{order_id}:
get:
description: 'Returns a confirmed order.
**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: getOrder
parameters:
- description: Order ID. You can get it by calling [Order:listOrders API](#/Order/listOrders).
in: path
name: order_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetOrderResponse'
description: The confirmed order information.
security:
- api_key: []
api_token: []
summary: Get a confirmed order
tags:
- Order
x-soracom-cli:
- orders get
/orders/{order_id}/cancel:
put:
description: Cancels an order. If the order has already been dispatched, an error is returned.
operationId: cancelOrder
parameters:
- description: Order ID. You can get it by calling [Order:listOrders API](#/Order/listOrders).
in: path
name: order_id
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema:
type: string
description: The order was cancelled.
security:
- api_key: []
api_token: []
summary: Cancel order
tags:
- Order
x-soracom-cli:
- orders cancel
/orders/{order_id}/confirm:
put:
description: 'Performs a credit limit and confirms the order if no problems are encountered.
**Warning**: Only orders completed within the past month can be confirmed. If one month has elapsed, please redo the
order placement operation.
'
operationId: confirmOrder
parameters:
- description: Order ID. You can get it by calling [Order:listOrders API](#/Order/listOrders).
in: path
name: order_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetOrderResponse'
description: The confirmed order information.
security:
- api_key: []
api_token: []
summary: Confirm order
tags:
- Order
x-soracom-cli:
- orders confirm
/orders/{order_id}/resource_initial_setting:
put:
description: 'Update resource initial setting for an order.
**Warning**: Initial settings of IoT SIM cannot be specified after confirmation of receipt.
'
operationId: updateOrderedResourceInitialSetting
parameters:
- description: Order ID. You can get it by calling [Order:listOrders API](#/Order/listOrders).
in: path
name: order_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceInitialSetting'
description: Resource initial setting for an order.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetOrderResponse'
description: The initial setting has been successfully updated.
'400':
content:
application/json:
schema:
type: string
description: The specified request has a problem.
'404':
content:
application/json:
schema:
type: string
description: Order ID not found.
security:
- api_key: []
api_token: []
summary: Update resource initial setting for an order
tags:
- Order
x-soracom-cli:
- orders resource-initial-setting update
/orders/{order_id}/subscribers:
get:
description: 'List ordered subscribers.
**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: listOrderedSubscribers
parameters:
- description: Order ID. You can get it by calling [Order:listOrders API](#/Order/listOrders).
in: path
name: order_id
required: true
schema:
type: string
- description: The value of the `x-soracom-next-key` header returned when the previous page was retrieved. Specify if
the next page is to be retrieved. For details, see [Handling Pagination](/en/docs/tools/api-reference/#handling-pagination).
in: query
name: last_evaluated_key
required: false
schema:
type: string
- description: Maximum number of subscribers in a response.
in: query
name: limit
required: false
schema:
format: int32
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListOrderedSubscriberResponse'
description: A list of ordered subscribers.
security:
- api_key: []
api_token: []
summary: List ordered subscribers
tags:
- Order
x-soracom-cli:
- orders list-subscribers
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
/orders/{order_id}/subscribers/register:
post:
description: 'Registers the ordered SIM with the operator.
**Warning**: IoT SIMs can only be registered for the past 18 months. If you need to register an IoT SIM that was ordered
before the time period, please contact [Soracom Support](https://support.soracom.io).
'
operationId: registerOrderedSim
parameters:
- description: Order ID. You can get it by calling [Order:listOrders API](#/Order/listOrders).
in: path
name: order_id
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema:
type: string
description: Subscribers were registered for the operator.
security:
- api_key: []
api_token: []
summary: Register subscribers for operator
tags:
- Order
x-soracom-cli:
- orders register-subscribers
/products:
get:
description: Returns a list of products.
operationId: listProducts
parameters:
- in: query
name: campaign_code
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListProductResponse'
description: A list of available products.
security:
- api_key: []
api_token: []
summary: List products
tags:
- Order
x-soracom-cli:
- products list
/volume_discounts/{order_id}/confirm:
put:
description: Performs a credit check and confirms the order if there are no issues.
operationId: confirmVolumeDiscountOrder
parameters:
- description: Order ID. The order
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/soracom/refs/heads/main/openapi/soracom-billing-api-openapi.yml