GET/api/v2/account/subscriptions
Subscription history
Paginated subscription periods and charges, plus freeMessageGrants. Sensitive internal fields are omitted.
When to use it. Show billing history or plan status in an external system.
Code example
Correct: First page
curl --location 'https://raselsms.com/api/v2/account/subscriptions' \--header 'X-API-Key: YOUR_API_KEY'Response example
200 — First page
{ "success": true, "data": { "subscriptions": [ { "id": "6800sub123def4567890aaaa", "planName": "Growth", "status": "active", "startAt": "2026-07-01T00:00:00.000Z", "endAt": "2026-08-01T00:00:00.000Z", "isTrial": false } ], "total": 1, "skip": 0, "limit": 20, "freeMessageGrants": { "summary": { "totals": { "granted": 100, "consumed": 10, "reserved": 0, "withdrawn": 0, "remaining": 90, "activeRemaining": 90 }, "activeGrantCount": 1, "grantCount": 1, "byScope": [ { "channel": "sms_local", "providerKey": null, "messageType": "all", "remaining": 90, "grantCount": 1 } ] }, "grants": [ { "id": "6800abc123def4567890fedc", "channel": "sms_local", "remainingQuantity": 90, "status": "active", "reason": "admin_gift" } ] } }}401 — Missing or invalid API key.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "UNAUTHORIZED", "error": "Missing or invalid API key"}403 — Phone is not verified or the key lacks permission (usually messages:create or api_keys:read).
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "FORBIDDEN", "error": "Phone not verified or missing permission"}429 — Rate limit exceeded. Honor Retry-After when present.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "RATE_LIMITED", "error": "Rate limit exceeded", "retryAfterSeconds": 30}HTTP request
GET /api/v2/account/subscriptions
Request Headers
| Header | Type | Description |
|---|---|---|
| X-API-Key | string | Your Rasel API key. Send it on every documented request except inbound webhooks. * |
Query parameters
| Field | Type | Description |
|---|---|---|
| skip | integer | Number of rows to skip. Default 0. |
| limit | integer | Page size. Typical range is 1-50 for conversation context and 1-500 for account lists. |
| status | pending | active | scheduled | expired | paused | cancelled | upgrade_pending | Delivery or record status. On send: sent, queued, or scheduled. On other resources it is the row status filter or value. |
| include | charges | subscriptions | Default includes both subscriptions and charges. Use subscriptions to omit charges. |
Response Fields
| Field | Type | Description | Example |
|---|---|---|---|
| success | boolean | True when the operation succeeded, or when at least one batch recipient succeeded. | |
| data | object | Primary payload for list and snapshot endpoints. | |
| data.subscriptions | json | Paged subscription periods. | |
| data.charges | json | Wallet charges included when the subscriptions request asks for them. | |
| data.freeMessageGrants | object | Complimentary admin gift message grants. | |
| data.freeMessageGrants.summary | object | Totals for complimentary message grants on this account. | |
| data.freeMessageGrants.summary.totals | object | Granted, consumed, reserved, withdrawn, and remaining gift messages. | |
| data.freeMessageGrants.summary.totals.granted | number | Gift messages that were issued. | |
| data.freeMessageGrants.summary.totals.consumed | number | Gift messages that were already used. | |
| data.freeMessageGrants.summary.totals.reserved | number | Gift messages held for sends that are still in flight. | |
| data.freeMessageGrants.summary.totals.withdrawn | number | Gift messages removed by an admin. | |
| data.freeMessageGrants.summary.totals.remaining | number | Gift messages that are still unused. | |
| data.freeMessageGrants.summary.totals.activeRemaining | number | Remaining messages on grants that are still active. | |
| data.freeMessageGrants.summary.activeGrantCount | integer | Number of grants that are still active. | |
| data.freeMessageGrants.summary.grantCount | integer | Total number of grants, including inactive ones. | |
| data.freeMessageGrants.summary.byScope | json | Remaining gift messages grouped by channel or scope. | |
| data.freeMessageGrants.grants | json | Individual complimentary message grants. | |
| data.totalSubscriptions | integer | Number of subscription periods matching the filter. | |
| data.totalCharges | integer | Number of charge rows matching the filter. | |
| data.skip | integer | Number of rows to skip. Default 0. | |
| data.limit | integer | Page size. Typical range is 1-50 for conversation context and 1-500 for account lists. |
Status Codes
| Status | Description |
|---|---|
| 200 | Success. |
| 401 | Missing or invalid API key. |
| 403 | Phone not verified, missing permission, or the account cannot perform this action. |
| 429 | Rate limit exceeded, or the maximum number of verification attempts was reached. |
Try it
Parameters
Number of rows to skip. Default 0.
Page size. Typical range is 1-50 for conversation context and 1-500 for account lists.
Delivery or record status. On send: sent, queued, or scheduled. On other resources it is the row status filter or value.
Default includes both subscriptions and charges. Use subscriptions to omit charges.
Request
GET /api/v2/account/subscriptions?status=pending&include=chargesResponse
Send a request to see the response.