Skip to content
iSmartPayDevelopers
Esc
↑↓navigate↵open⌘Jpreview

List subscriptions

Your business’s subscriptions, newest first. Pass nextAfter as after to read the next page. Requires the mandates.read permission.

GET/v1/subscriptions
Authorization
AuthorizationBearer token (JWT) · headerrequired

A token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.

Query parameters
statusstring

Only subscriptions in this state. A trialing subscription is listed under active, and an unpaid one under past_due.

Allowed:incompleteincomplete_expiredactivepast_duepausedcanceledcompleted
limitinteger

How many to return, 1 to 100. Defaults to 50.

min 1 · max 100 · default: 50
afterstring

The nextAfter of the previous page.

max length 512
Responses
200

A page of subscriptions.

itemsSubscription[]required
Show properties
Array of Subscription
idstringrequired
matches ^sub_[0-9a-f]{32}$
referencestringrequired
statusstringrequired

incomplete: waiting for the customer. incomplete_expired: they declined or never answered; see declineReason. trialing: approved, with the first charge still to come. active: charging on schedule. past_due: every retry of a cycle failed; pastDueBehavior says what happens next. unpaid: past due with pastDueBehavior keep_charging. paused: no charges. canceled: see cancelReason. completed: reached endDate or maxCycles.

Allowed:incompleteincomplete_expiredtrialingactivepast_dueunpaidpausedcanceledcompleted
customerobjectrequired
Show properties
phonestringrequired
networkstring
Allowed:mtntelecel
paymentMethodstringrequired
Allowed:mobile_moneywallet
priceDataobjectrequired
Show properties
amountstringrequired

A decimal string in major units.

currencystringrequired
intervalstringrequired
Allowed:dayweekmonth
intervalCountintegerrequired
Allowed:1
feestringrequired

The fee the customer pays on each charge, fixed when the subscription was created. A decimal string in major units.

totalAmountstringrequired

What the customer pays on each charge: priceData.amount plus fee.

startDatestring<date>required
endDatestring<date>
maxCyclesinteger
billingTimestringrequired
timezonestringrequired
retryobjectrequired
Show properties
afterDaysinteger[]
pastDueBehaviorstringrequired
Allowed:cancelpausekeep_charging
descriptionstring
consentobjectrequired

How the customer agrees.

Show properties
channelstringrequired

network: their network asks them to approve. first_charge: the first charge's prompt is the agreement. pin: they approve with their PIN in the iSmartPay app.

Allowed:networkfirst_chargepin
expiresAtstring<date-time>

When the request lapses if the customer has not answered.

consentedAtstring<date-time>
nextChargeAtstring<date-time> | nullrequired

When the next charge is due, or null when none is.

cyclesChargedintegerrequired

How many cycles have been paid.

cancelAtPeriodEndbooleanrequired
cancelAtstring<date-time>

When a subscription set to end at its period end will end.

cancelReasonstring

Present when canceled: you canceled it, the customer canceled the agreement with their network, or iSmartPay did.

Allowed:businessnetworkplatform
declineReasonstring

Present when incomplete_expired.

Allowed:declinedno_response
pausedBystring

Present when paused. platform means iSmartPay stopped charging; contact support.

Allowed:businessplatform
createdAtstring<date-time>required
updatedAtstring<date-time>required
nextAfterstring

Pass as after to read the next page. Absent on the last page.

400

The request is not valid. message says which field.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

401

The token is missing, expired or not valid. Get a new one from the token endpoint.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

403

The request was understood and refused. Common causes: the token is not an API credential's (forbidden); the credential is for the other environment (environment_mismatch); it does not have the permission this operation needs (forbidden); a limit was reached (limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit); or iSmartPay has suspended or deactivated the business (business_suspended, business_deactivated). A suspended business's API credentials stop exchanging for tokens, so a request made with a token issued just before the suspension is refused with business_suspended.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

429

Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

500

Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

502

A service behind the API did not answer usably. If the request was a POST, retry with the same Idempotency-Key and body. A party lookup the provider rejects is provider_error.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

503

The API is temporarily unable to tell which environment it serves (environment_unknown), utility purchases are not available right now (utilities_unavailable), a settlement destination could not be name-checked just now (destination_verification_unavailable; retry the same request), or hosted checkout is not set up on this deployment (checkout_unavailable). Retry shortly, except for checkout_unavailable, which lasts until the deployment is configured.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

504

The request took too long. If it was a POST, its outcome is unknown: retry with the same Idempotency-Key and body, or read it back by reference. A party lookup the provider does not answer is provider_timeout: check again before relying on it.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

Request
curl -X GET 'https://stgdeveloper-api.ismartghana.com/v1/subscriptions' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "items": [
    {
      "id": "sub_0f1d6a3c7b114a549a3b6f1c2f0e8f6e",
      "reference": "string",
      "status": "incomplete",
      "customer": {
        "phone": "string",
        "network": "mtn"
      },
      "paymentMethod": "mobile_money",
      "priceData": {
        "amount": "150.00",
        "currency": "GHS",
        "interval": "day",
        "intervalCount": 1
      },
      "fee": "2.25",
      "totalAmount": "152.25",
      "startDate": "2019-08-24",
      "endDate": "2019-08-24",
      "maxCycles": 0,
      "billingTime": "09:00",
      "timezone": "Africa/Accra",
      "retry": {
        "afterDays": [
          0
        ]
      },
      "pastDueBehavior": "cancel",
      "description": "string",
      "consent": {
        "channel": "network",
        "expiresAt": "2019-08-24T14:15:22Z",
        "consentedAt": "2019-08-24T14:15:22Z"
      },
      "nextChargeAt": "2019-08-24T14:15:22Z",
      "cyclesCharged": 0,
      "cancelAtPeriodEnd": true,
      "cancelAt": "2019-08-24T14:15:22Z",
      "cancelReason": "business",
      "declineReason": "declined",
      "pausedBy": "business",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "nextAfter": "string"
}