API reference

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with prod_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.
`description` required	`string`	A short text shown to people.
`active` required	`boolean`	True while the product can be sold.
`createdAt` required	`string (date-time)`	When it was created.

GET/v1/products/{productId}

Retrieve a product.

Parameters

Name	Type	Description
`productId (path)` required	`string`	The product's id, starting prod_. (starts with prod_)

Response 200

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with prod_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.
`description` required	`string`	A short text shown to people.
`active` required	`boolean`	True while the product can be sold.
`createdAt` required	`string (date-time)`	When it was created.

GET/v1/products/{productId}/prices

List the prices of a product.

Parameters

Name	Type	Description
`productId (path)` required	`string`	The product's id, starting prod_. (starts with prod_)
`limit (query)`	`integer`	The most items to return in one page. (1 to 100; default 50)
`cursor (query)`	`string or null`	The nextCursor from the previous page, to continue the list. (0 to 512 characters)

Response 200

PriceListResponse

Name	Type	Description
`data` required	`Price[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.

POST/v1/products/{productId}/prices

Add a price to a product.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`productId (path)` required	`string`	The product's id, starting prod_. (starts with prod_)

Request body

CreatePriceRequest

Name	Type	Description
`amount` required	`PriceAmount`	What the price charges each period.

Response 201

Price

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with price_)
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`amount` required	`Money`	What the price charges each period.
`createdAt` required	`string (date-time)`	When it was created.

Invoices and checkout

GET/v1/invoices

List invoices, newest first, one page at a time.

Parameters

Name	Type	Description
`status (query)`	`string or null`	Only invoices with this payment status. An unknown payment result is its own status. (0 to 32 characters)
`dueFrom (query)`	`string (date-time) or null`	Only invoices due at or after this time.
`dueTo (query)`	`string (date-time) or null`	Only invoices due at or before this time.
`customerId (query)`	`string or null`	Only this customer's invoices. (0 to 64 characters)
`limit (query)`	`integer or null`	The most items to return in one page. (1 to 500)
`cursor (query)`	`string or null`	The nextCursor from the previous page, to continue the list. (0 to 1024 characters)
`q (query)`	`string or null`	Search text. Matches the invoice id, description, reference, customer name or the last digits of a phone, ignoring case. (0 to 400 characters)
`sort (query)`	`string or null`	The order of the list: created_at, due_at or amount, followed by :asc or :desc. The default is created_at:desc. (0 to 32 characters)
`includeTotal (query)`	`boolean`	Set to false to skip counting the matching invoices when you only need the page. (default true)

Response 200

Name	Type	Description
`data` required	`Invoice[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.
`totalCount`	`integer or null`	How many items match the filter, across all pages. Exact up to 1000.
`totalCountCapped`	`boolean`	True when totalCount stopped counting at its limit, so more items match than it shows. (default false)

POST/v1/invoices

Create an invoice for a customer.

Send an Idempotency-Key header.

Request body

CreateInvoiceRequest

Name	Type	Description
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`amount` required	`Money`	The amount, as a money object.
`description` required	`string`	What the invoice is for. The customer sees it. (1 to 240 characters)
`dueAt` required	`string (date-time)`	When payment is due.
`reference` required	`string`	Your own reference, such as an order number. (1 to 120 characters)

Response 201

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with inv_)
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`sellerName` required	`string`	The seller name shown to the customer.
`description` required	`string`	A short text shown to people.
`amount` required	`Money`	The amount, as a money object.
`dueAt` required	`string (date-time)`	When payment is due.
`status` required	`"open" \| "paid" \| "void"`	open until a confirmed payment, then paid. void if the invoice was cancelled.
`paymentStatus` required	`"due" \| "pending" \| "unknown" \| "succeeded" \| "failed"`	Whether the customer has paid. unknown means the result could not be confirmed yet; it is not a failure.
`reconciliationStatus` required	`"not_applicable" \| "unmatched" \| "matched" \| "exception"`	Whether the confirmed payment has been matched to this invoice.
`settlementStatus` required	`"not_reported" \| "pending" \| "settled" \| "held" \| "reversed"`	Whether the provider has reported the money as settled to you.
`paidAttemptId` required	`string or null`	The payment attempt that paid this invoice, or null. (starts with payatt_)
`paidWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer paid with, or null.
`paidDestinationMasked` required	`string or null`	The paying number with the middle digits hidden, or null.
`nextRenewalAt` required	`string (date-time) or null`	When the subscription behind this invoice bills next, or null.
`nextRenewalTimezone` required	`string or null`	The time zone of nextRenewalAt, or null.
`subscriptionId`	`string or null`	The subscription that produced this invoice, if any. (starts with sub_)
`issuedAt` required	`string (date-time) or null`	When the invoice was issued, or null.
`paidAt` required	`string (date-time) or null`	When the payment was confirmed, or null.
`eligibility` required	`InvoiceEligibility`	Whether a payment link or reminder can be sent for this invoice now.

GET/v1/invoices/{invoiceId}

Retrieve an invoice with its payment, reconciliation and settlement states.

Parameters

Name	Type	Description
`invoiceId (path)` required	`string`	The invoice's id, starting inv_. (starts with inv_)

Response 200

SubscriptionListResponse

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with inv_)
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`sellerName` required	`string`	The seller name shown to the customer.
`description` required	`string`	A short text shown to people.
`amount` required	`Money`	The amount, as a money object.
`dueAt` required	`string (date-time)`	When payment is due.
`status` required	`"open" \| "paid" \| "void"`	open until a confirmed payment, then paid. void if the invoice was cancelled.
`paymentStatus` required	`"due" \| "pending" \| "unknown" \| "succeeded" \| "failed"`	Whether the customer has paid. unknown means the result could not be confirmed yet; it is not a failure.
`reconciliationStatus` required	`"not_applicable" \| "unmatched" \| "matched" \| "exception"`	Whether the confirmed payment has been matched to this invoice.
`settlementStatus` required	`"not_reported" \| "pending" \| "settled" \| "held" \| "reversed"`	Whether the provider has reported the money as settled to you.
`paidAttemptId` required	`string or null`	The payment attempt that paid this invoice, or null. (starts with payatt_)
`paidWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer paid with, or null.
`paidDestinationMasked` required	`string or null`	The paying number with the middle digits hidden, or null.
`nextRenewalAt` required	`string (date-time) or null`	When the subscription behind this invoice bills next, or null.
`nextRenewalTimezone` required	`string or null`	The time zone of nextRenewalAt, or null.
`subscriptionId`	`string or null`	The subscription that produced this invoice, if any. (starts with sub_)
`issuedAt` required	`string (date-time) or null`	When the invoice was issued, or null.
`paidAt` required	`string (date-time) or null`	When the payment was confirmed, or null.
`eligibility` required	`InvoiceEligibility`	Whether a payment link or reminder can be sent for this invoice now.

POST/v1/invoices/{invoiceId}/checkout-sessions

Create an expiring hosted payment link for an invoice.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`invoiceId (path)` required	`string`	The invoice's id, starting inv_. (starts with inv_)

Request body

Name	Type	Description
`expiresAt` required	`string (date-time)`	When it stops working.
`returnUrl`	`string or null`	Where to send the customer after they leave the payment page. Never proof of payment. (1 to 2048 characters)

Response 201

CheckoutSessionCreated

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with chk_)
`checkoutUrl` required	`string (uri)`	The hosted payment page for the customer. It appears in this response only.
`expiresAt` required	`string (date-time)`	When it stops working.

Payments

GET/v1/payment-attempts/{attemptId}

Retrieve one payment attempt and its current status.

Parameters

Name	Type	Description
`attemptId (path)` required	`string`	The payment attempt's id, starting payatt_. (starts with payatt_)

Response 200

PaymentAttempt

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with payatt_)
`invoiceId` required	`string`	The invoice this attempt pays. (starts with inv_)
`status` required	`PaymentAttemptStatus`	How far the attempt has got. See the payment guide.
`amount` required	`Money`	The amount the customer was asked to pay.
`wallet` required	`"mpesa"`	The wallet used.
`nextAction` required	`"await_provider" \| "await_wallet_authorisation" \| "wait_for_update" \| "correct_phone" \| "create_new_attempt" \| "contact_support" \| null`	What is safe to do next. wait_for_update means wait.
`failureCode` required	`PaymentFailureCode or null`	Why the attempt failed, or null.
`destinationMasked` required	`string or null`	The paying number with the middle digits hidden, or null.
`statusOccurredAt` required	`string (date-time) or null`	When the status last changed, or null.

Subscriptions

GET/v1/subscriptions

List subscriptions.

Parameters

Name	Type	Description
`limit (query)`	`integer`	The most items to return in one page. (1 to 500; default 200)
`cursor (query)`	`string or null`	The nextCursor from the previous page, to continue the list. (0 to 512 characters)

Response 200

Name	Type	Description
`data` required	`Subscription[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.

POST/v1/subscriptions

Subscribe a customer to a product price.

Send an Idempotency-Key header.

Request body

CreateSubscriptionRequest

Name	Type	Description
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`priceId` required	`string`	The price's id, starting price_. (starts with price_)
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`start`	`"current_period" \| "next_period"`	next_period begins at the next anchor and invoices nothing until then. current_period starts the period containing today and invoices at once.

Response 201

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

GET/v1/subscriptions/{subscriptionId}

Retrieve a subscription.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Response 200

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

POST/v1/subscriptions/{subscriptionId}/pause

Pause a subscription.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Request body

Name	Type	Description
`reason` required	`string`	Why you are making this change, kept with the record. (1 to 240 characters)

Response 200

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

POST/v1/subscriptions/{subscriptionId}/resume

Resume a paused subscription.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Request body

Name	Type	Description
`reason` required	`string`	Why you are making this change, kept with the record. (1 to 240 characters)

Response 200

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

POST/v1/subscriptions/{subscriptionId}/cancel

Cancel a subscription.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Request body

SubscriptionCancellation

Name	Type	Description
`reason` required	`string`	Why you are making this change, kept with the record. (1 to 240 characters)

Response 200

Name	Type	Description
`subscription` required	`Subscription`	The subscription after the change.
`voidedInvoiceIds` required	`string[]`	Invoices voided by the cancellation.
`invoicesKeptForPaymentInFlight` required	`string[]`	Invoices left open because a payment on them is still in progress.

GET/v1/subscriptions/{subscriptionId}/billing-cycles

List the billing cycles of a subscription.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Response 200

BillingCycleListResponse

Name	Type	Description
`data` required	`BillingCycle[]`	The items on this page.

POST/v1/enrollment-links

Create a hosted link customers use to subscribe themselves.

Send an Idempotency-Key header.

Request body

CreateEnrollmentLinkRequest

Name	Type	Description
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`priceId` required	`string`	The price's id, starting price_. (starts with price_)
`cadence` required	`"monthly"`	How often a billing period starts.
`anchorDay` required	`integer`	The day of the month each period starts, 1 to 28. (1 to 28)
`timezone` required	`"Africa/Nairobi"`	The time zone periods run on.
`expiresAt`	`string (date-time) or null`	When it stops working.

Response 201

EnrollmentLinkCreated

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with enr_)
`enrollmentUrl` required	`string (uri)`	The hosted page for the customer to sign themselves up. It appears in this response only.
`expiresAt` required	`string (date-time)`	When it stops working.

POST/v1/enrollment-links/{enrollmentLinkId}/revoke

Revoke a sign-up link.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`enrollmentLinkId (path)` required	`string`	The sign-up link's id. (starts with enr_)

Request body

RevokeEnrollmentLinkRequest

Name	Type	Description
`reason` required	`string`	Why you are making this change, kept with the record. (1 to 240 characters)

Response 200

EnrollmentLink

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with enr_)
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`priceId` required	`string`	The price's id, starting price_. (starts with price_)
`cadence` required	`"monthly"`	How often a billing period starts.
`state` required	`"active" \| "revoked"`	active until revoked.
`expiresAt` required	`string (date-time)`	When it stops working.
`createdAt` required	`string (date-time)`	When it was created.
`revokedAt` required	`string (date-time) or null`	When it was revoked, or null.
`revokeReason` required	`string or null`	The reason given when it was revoked, or null.

Objects

ActionEligibility

Name	Type	Description
`eligible` required	`boolean`	True when the action can be taken now.
`reason` required	`"invoice_paid" \| "invoice_closed" \| "payment_state_unknown" \| "payment_attempt_pending" \| "checkout_unavailable" \| "already_sent" \| "no_prior_delivery" \| "delivery_in_flight" \| "delivery_outcome_unknown" \| "no_consent" \| "suppressed" \| "contact_suppressed" \| "no_eligible_contact_point" \| "contact_cap_reached" \| "quiet_hours" \| "channel_not_configured" \| "channel_disabled" \| "channel_unavailable" \| "recovery_attempts_exhausted" \| "recovery_outcome_unknown" \| null`	Why the action cannot be taken now, or null.

BillingCycle

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with cyc_)
`subscriptionId` required	`string`	The subscription's id, starting sub_. (starts with sub_)
`sequence` required	`integer`	The cycle's position, starting at 1.
`periodKey` required	`string`	An identifier for the billing period within the subscription.
`periodStart` required	`string (date-time)`	When the period starts.
`periodEnd` required	`string (date-time)`	When the period ends.
`state` required	`"pending" \| "invoiced" \| "skipped"`	pending before the invoice is issued, invoiced once it is, or skipped.
`invoice` required	`BillingCycleInvoiceRef or null`	The invoice issued for this period, or null.
`entitledAt` required	`string (date-time) or null`	When the period became paid for, which is when the invoice was paid, or null before then.

BillingCycleInvoiceRef

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with inv_)
`state` required	`string`	The invoice's state: open, paid or void.
`amount` required	`Money`	The amount, as a money object.
`paymentStatus`	`"due" \| "pending" \| "unknown" \| "succeeded" \| "failed" or null`	Whether the customer has paid. unknown means the result could not be confirmed yet; it is not a failure.
`dueAt`	`string (date-time) or null`	When payment is due.

BillingCycleListResponse

Name	Type	Description
`data` required	`BillingCycle[]`	The items on this page.

CheckoutSessionCreated

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with chk_)
`checkoutUrl` required	`string (uri)`	The hosted payment page for the customer. It appears in this response only.
`expiresAt` required	`string (date-time)`	When it stops working.

CreateCustomerRequest

Name	Type	Description
`reference` required	`string`	Your own identifier for this record, so you can match it to your system. (1 to 120 characters)
`name` required	`string`	The display name. (1 to 160 characters)
`phone` required	`string`	The customer's Kenyan mobile number in international format.
`notificationPhone`	`string or null`	A number to send messages to, when it differs from the main number.
`paymentPhone`	`string or null`	A number to take payments from, when it differs from the main number.
`smsConsentAttested`	`boolean or null`	Set true only if the customer has agreed to receive payment requests by SMS from you.

CreateEnrollmentLinkRequest

Name	Type	Description
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`priceId` required	`string`	The price's id, starting price_. (starts with price_)
`cadence` required	`"monthly"`	How often a billing period starts.
`anchorDay` required	`integer`	The day of the month each period starts, 1 to 28. (1 to 28)
`timezone` required	`"Africa/Nairobi"`	The time zone periods run on.
`expiresAt`	`string (date-time) or null`	When it stops working.

CreateInvoiceRequest

Name	Type	Description
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`amount` required	`Money`	The amount, as a money object.
`description` required	`string`	What the invoice is for. The customer sees it. (1 to 240 characters)
`dueAt` required	`string (date-time)`	When payment is due.
`reference` required	`string`	Your own reference, such as an order number. (1 to 120 characters)

CreatePriceRequest

Name	Type	Description
`amount` required	`PriceAmount`	What the price charges each period.

CreateProductRequest

Name	Type	Description
`reference` required	`string`	Your own identifier for this record, so you can match it to your system. (1 to 120 characters)
`name` required	`string`	The display name. (1 to 160 characters)
`description` required	`string`	What the product is, in a sentence. (1 to 1024 characters)

CreateSubscriptionRequest

Name	Type	Description
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`priceId` required	`string`	The price's id, starting price_. (starts with price_)
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`start`	`"current_period" \| "next_period"`	next_period begins at the next anchor and invoices nothing until then. current_period starts the period containing today and invoices at once.

Customer

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with cus_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.
`phoneMasked` required	`string`	The customer's number with the middle digits hidden. The full number is never returned.
`paymentPhoneMasked` required	`string`	The payment number with the middle digits hidden.
`suppressed` required	`boolean`	True when messages to this customer are turned off.
`consentActive` required	`boolean`	True when the customer has agreed to receive payment requests by SMS.
`createdAt` required	`string (date-time) or null`	When it was created.
`lastPayment`	`CustomerLastPayment or null`	The customer's most recent confirmed payment, or null.
`openBalance`	`Money or null`	What the customer owes across invoices that are open. An unknown payment result is left out. Null when unavailable.
`hasUnknownPayment`	`boolean`	True when one of this customer's payments has an unknown result. (default false)
`hasPastDue`	`boolean`	True when this customer has an invoice past its due date. (default false)

CustomerLastPayment

Name	Type	Description
`amount` required	`Money`	The amount paid.
`paidAt` required	`string (date-time)`	When the payment was confirmed.

EnrollmentLink

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with enr_)
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`priceId` required	`string`	The price's id, starting price_. (starts with price_)
`cadence` required	`"monthly"`	How often a billing period starts.
`state` required	`"active" \| "revoked"`	active until revoked.
`expiresAt` required	`string (date-time)`	When it stops working.
`createdAt` required	`string (date-time)`	When it was created.
`revokedAt` required	`string (date-time) or null`	When it was revoked, or null.
`revokeReason` required	`string or null`	The reason given when it was revoked, or null.

EnrollmentLinkCreated

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with enr_)
`enrollmentUrl` required	`string (uri)`	The hosted page for the customer to sign themselves up. It appears in this response only.
`expiresAt` required	`string (date-time)`	When it stops working.

Invoice

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with inv_)
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`sellerName` required	`string`	The seller name shown to the customer.
`description` required	`string`	A short text shown to people.
`amount` required	`Money`	The amount, as a money object.
`dueAt` required	`string (date-time)`	When payment is due.
`status` required	`"open" \| "paid" \| "void"`	open until a confirmed payment, then paid. void if the invoice was cancelled.
`paymentStatus` required	`"due" \| "pending" \| "unknown" \| "succeeded" \| "failed"`	Whether the customer has paid. unknown means the result could not be confirmed yet; it is not a failure.
`reconciliationStatus` required	`"not_applicable" \| "unmatched" \| "matched" \| "exception"`	Whether the confirmed payment has been matched to this invoice.
`settlementStatus` required	`"not_reported" \| "pending" \| "settled" \| "held" \| "reversed"`	Whether the provider has reported the money as settled to you.
`paidAttemptId` required	`string or null`	The payment attempt that paid this invoice, or null. (starts with payatt_)
`paidWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer paid with, or null.
`paidDestinationMasked` required	`string or null`	The paying number with the middle digits hidden, or null.
`nextRenewalAt` required	`string (date-time) or null`	When the subscription behind this invoice bills next, or null.
`nextRenewalTimezone` required	`string or null`	The time zone of nextRenewalAt, or null.
`subscriptionId`	`string or null`	The subscription that produced this invoice, if any. (starts with sub_)
`issuedAt` required	`string (date-time) or null`	When the invoice was issued, or null.
`paidAt` required	`string (date-time) or null`	When the payment was confirmed, or null.
`eligibility` required	`InvoiceEligibility`	Whether a payment link or reminder can be sent for this invoice now.

InvoiceEligibility

Name	Type	Description
`sendPaymentLink` required	`ActionEligibility`	Whether a first payment link can be sent.
`resendPaymentLink` required	`ActionEligibility`	Whether the payment link can be sent again.
`sendReminder` required	`ActionEligibility`	Whether a reminder can be sent.

Money

Name	Type	Description
`minor` required	`string`	The amount in integer minor units, sent as a string. KES 1,350.00 is "135000".
`currency` required	`"KES"`	The currency. Only KES is supported.

PaymentAttempt

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with payatt_)
`invoiceId` required	`string`	The invoice this attempt pays. (starts with inv_)
`status` required	`PaymentAttemptStatus`	How far the attempt has got. See the payment guide.
`amount` required	`Money`	The amount the customer was asked to pay.
`wallet` required	`"mpesa"`	The wallet used.
`nextAction` required	`"await_provider" \| "await_wallet_authorisation" \| "wait_for_update" \| "correct_phone" \| "create_new_attempt" \| "contact_support" \| null`	What is safe to do next. wait_for_update means wait.
`failureCode` required	`PaymentFailureCode or null`	Why the attempt failed, or null.
`destinationMasked` required	`string or null`	The paying number with the middle digits hidden, or null.
`statusOccurredAt` required	`string (date-time) or null`	When the status last changed, or null.

PaymentAttemptStatus

One of: created, initiation_queued, initiation_rejected, customer_action_required, provider_accepted, unknown, failed, cancelled, expired, succeeded, reversed

PaymentFailureCode

One of: customer_cancelled, insufficient_funds, invalid_customer_account, customer_limit_exceeded, payment_expired, duplicate_request, merchant_disabled, compliance_block, capability_unavailable, provider_unavailable, provider_rate_limited, invalid_provider_configuration, unknown_provider_result, provider_rejected

Price

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with price_)
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`amount` required	`Money`	What the price charges each period.
`createdAt` required	`string (date-time)`	When it was created.

PriceAmount

Name	Type	Description
`minor` required	`string`	The amount in integer minor units, sent as a string. KES 1,350.00 is "135000". (0 to 11 characters)
`currency` required	`"KES"`	The currency. Only KES is supported.

PriceListResponse

Name	Type	Description
`data` required	`Price[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.

Product

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with prod_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.
`description` required	`string`	A short text shown to people.
`active` required	`boolean`	True while the product can be sold.
`createdAt` required	`string (date-time)`	When it was created.

ProductListResponse

Name	Type	Description
`data` required	`Product[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.

RevokeEnrollmentLinkRequest

Name	Type	Description
`reason` required	`string`	Why you are making this change, kept with the record. (1 to 240 characters)

Subscription

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

SubscriptionAnchor

Name	Type	Description
`dayOfMonth`	`integer or null`	The day of the month, 1 to 28. Set for monthly. (1 to 28)
`weekday`	`integer or null`	The ISO weekday, 1 for Monday to 7 for Sunday. Set for weekly. (1 to 7)

SubscriptionCancellation

Name	Type	Description
`subscription` required	`Subscription`	The subscription after the change.
`voidedInvoiceIds` required	`string[]`	Invoices voided by the cancellation.
`invoicesKeptForPaymentInFlight` required	`string[]`	Invoices left open because a payment on them is still in progress.

SubscriptionCustomerRef

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with cus_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.

SubscriptionLifecycleRequest

Name	Type	Description
`reason` required	`string`	Why you are making this change, kept with the record. (1 to 240 characters)

SubscriptionListResponse

Name	Type	Description
`data` required	`Subscription[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.

SubscriptionPriceRef

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with price_)
`amount` required	`Money`	The amount, as a money object.

SubscriptionProductRef

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with prod_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.

API reference

Every endpoint you can call with an API key, with its parameters, bodies and responses.

Conventions

Customers

POST/v1/customers

Add a customer.

Send an Idempotency-Key header.

Request body

CreateCustomerRequest

Name	Type	Description
`reference` required	`string`	Your own identifier for this record, so you can match it to your system. (1 to 120 characters)
`name` required	`string`	The display name. (1 to 160 characters)
`phone` required	`string`	The customer's Kenyan mobile number in international format.
`notificationPhone`	`string or null`	A number to send messages to, when it differs from the main number.
`paymentPhone`	`string or null`	A number to take payments from, when it differs from the main number.
`smsConsentAttested`	`boolean or null`	Set true only if the customer has agreed to receive payment requests by SMS from you.

Response 201

Customer

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with cus_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.
`phoneMasked` required	`string`	The customer's number with the middle digits hidden. The full number is never returned.
`paymentPhoneMasked` required	`string`	The payment number with the middle digits hidden.
`suppressed` required	`boolean`	True when messages to this customer are turned off.
`consentActive` required	`boolean`	True when the customer has agreed to receive payment requests by SMS.
`createdAt` required	`string (date-time) or null`	When it was created.
`lastPayment`	`CustomerLastPayment or null`	The customer's most recent confirmed payment, or null.
`openBalance`	`Money or null`	What the customer owes across invoices that are open. An unknown payment result is left out. Null when unavailable.
`hasUnknownPayment`	`boolean`	True when one of this customer's payments has an unknown result. (default false)
`hasPastDue`	`boolean`	True when this customer has an invoice past its due date. (default false)

Products and prices

GET/v1/products

List your products.

Parameters

Name	Type	Description
`limit (query)`	`integer`	The most items to return in one page. (1 to 100; default 50)
`cursor (query)`	`string or null`	The nextCursor from the previous page, to continue the list. (0 to 512 characters)

Response 200

ProductListResponse

Name	Type	Description
`data` required	`Product[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.

POST/v1/products

Create a product.

Send an Idempotency-Key header.

Request body

CreateProductRequest

Name	Type	Description
`reference` required	`string`	Your own identifier for this record, so you can match it to your system. (1 to 120 characters)
`name` required	`string`	The display name. (1 to 160 characters)
`description` required	`string`	What the product is, in a sentence. (1 to 1024 characters)

Response 201

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with prod_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.
`description` required	`string`	A short text shown to people.
`active` required	`boolean`	True while the product can be sold.
`createdAt` required	`string (date-time)`	When it was created.

GET/v1/products/{productId}

Retrieve a product.

Parameters

Name	Type	Description
`productId (path)` required	`string`	The product's id, starting prod_. (starts with prod_)

Response 200

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with prod_)
`reference` required	`string`	Your own identifier for this record, so you can match it to your system.
`name` required	`string`	The display name.
`description` required	`string`	A short text shown to people.
`active` required	`boolean`	True while the product can be sold.
`createdAt` required	`string (date-time)`	When it was created.

GET/v1/products/{productId}/prices

List the prices of a product.

Parameters

Name	Type	Description
`productId (path)` required	`string`	The product's id, starting prod_. (starts with prod_)
`limit (query)`	`integer`	The most items to return in one page. (1 to 100; default 50)
`cursor (query)`	`string or null`	The nextCursor from the previous page, to continue the list. (0 to 512 characters)

Response 200

PriceListResponse

Name	Type	Description
`data` required	`Price[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.

POST/v1/products/{productId}/prices

Add a price to a product.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`productId (path)` required	`string`	The product's id, starting prod_. (starts with prod_)

Request body

CreatePriceRequest

Name	Type	Description
`amount` required	`PriceAmount`	What the price charges each period.

Response 201

Price

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with price_)
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`amount` required	`Money`	What the price charges each period.
`createdAt` required	`string (date-time)`	When it was created.

Invoices and checkout

GET/v1/invoices

List invoices, newest first, one page at a time.

Parameters

Name	Type	Description
`status (query)`	`string or null`	Only invoices with this payment status. An unknown payment result is its own status. (0 to 32 characters)
`dueFrom (query)`	`string (date-time) or null`	Only invoices due at or after this time.
`dueTo (query)`	`string (date-time) or null`	Only invoices due at or before this time.
`customerId (query)`	`string or null`	Only this customer's invoices. (0 to 64 characters)
`limit (query)`	`integer or null`	The most items to return in one page. (1 to 500)
`cursor (query)`	`string or null`	The nextCursor from the previous page, to continue the list. (0 to 1024 characters)
`q (query)`	`string or null`	Search text. Matches the invoice id, description, reference, customer name or the last digits of a phone, ignoring case. (0 to 400 characters)
`sort (query)`	`string or null`	The order of the list: created_at, due_at or amount, followed by :asc or :desc. The default is created_at:desc. (0 to 32 characters)
`includeTotal (query)`	`boolean`	Set to false to skip counting the matching invoices when you only need the page. (default true)

Response 200

Name	Type	Description
`data` required	`Invoice[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.
`totalCount`	`integer or null`	How many items match the filter, across all pages. Exact up to 1000.
`totalCountCapped`	`boolean`	True when totalCount stopped counting at its limit, so more items match than it shows. (default false)

POST/v1/invoices

Create an invoice for a customer.

Send an Idempotency-Key header.

Request body

CreateInvoiceRequest

Name	Type	Description
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`amount` required	`Money`	The amount, as a money object.
`description` required	`string`	What the invoice is for. The customer sees it. (1 to 240 characters)
`dueAt` required	`string (date-time)`	When payment is due.
`reference` required	`string`	Your own reference, such as an order number. (1 to 120 characters)

Response 201

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with inv_)
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`sellerName` required	`string`	The seller name shown to the customer.
`description` required	`string`	A short text shown to people.
`amount` required	`Money`	The amount, as a money object.
`dueAt` required	`string (date-time)`	When payment is due.
`status` required	`"open" \| "paid" \| "void"`	open until a confirmed payment, then paid. void if the invoice was cancelled.
`paymentStatus` required	`"due" \| "pending" \| "unknown" \| "succeeded" \| "failed"`	Whether the customer has paid. unknown means the result could not be confirmed yet; it is not a failure.
`reconciliationStatus` required	`"not_applicable" \| "unmatched" \| "matched" \| "exception"`	Whether the confirmed payment has been matched to this invoice.
`settlementStatus` required	`"not_reported" \| "pending" \| "settled" \| "held" \| "reversed"`	Whether the provider has reported the money as settled to you.
`paidAttemptId` required	`string or null`	The payment attempt that paid this invoice, or null. (starts with payatt_)
`paidWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer paid with, or null.
`paidDestinationMasked` required	`string or null`	The paying number with the middle digits hidden, or null.
`nextRenewalAt` required	`string (date-time) or null`	When the subscription behind this invoice bills next, or null.
`nextRenewalTimezone` required	`string or null`	The time zone of nextRenewalAt, or null.
`subscriptionId`	`string or null`	The subscription that produced this invoice, if any. (starts with sub_)
`issuedAt` required	`string (date-time) or null`	When the invoice was issued, or null.
`paidAt` required	`string (date-time) or null`	When the payment was confirmed, or null.
`eligibility` required	`InvoiceEligibility`	Whether a payment link or reminder can be sent for this invoice now.

GET/v1/invoices/{invoiceId}

Retrieve an invoice with its payment, reconciliation and settlement states.

Parameters

Name	Type	Description
`invoiceId (path)` required	`string`	The invoice's id, starting inv_. (starts with inv_)

Response 200

SubscriptionListResponse

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with inv_)
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`sellerName` required	`string`	The seller name shown to the customer.
`description` required	`string`	A short text shown to people.
`amount` required	`Money`	The amount, as a money object.
`dueAt` required	`string (date-time)`	When payment is due.
`status` required	`"open" \| "paid" \| "void"`	open until a confirmed payment, then paid. void if the invoice was cancelled.
`paymentStatus` required	`"due" \| "pending" \| "unknown" \| "succeeded" \| "failed"`	Whether the customer has paid. unknown means the result could not be confirmed yet; it is not a failure.
`reconciliationStatus` required	`"not_applicable" \| "unmatched" \| "matched" \| "exception"`	Whether the confirmed payment has been matched to this invoice.
`settlementStatus` required	`"not_reported" \| "pending" \| "settled" \| "held" \| "reversed"`	Whether the provider has reported the money as settled to you.
`paidAttemptId` required	`string or null`	The payment attempt that paid this invoice, or null. (starts with payatt_)
`paidWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer paid with, or null.
`paidDestinationMasked` required	`string or null`	The paying number with the middle digits hidden, or null.
`nextRenewalAt` required	`string (date-time) or null`	When the subscription behind this invoice bills next, or null.
`nextRenewalTimezone` required	`string or null`	The time zone of nextRenewalAt, or null.
`subscriptionId`	`string or null`	The subscription that produced this invoice, if any. (starts with sub_)
`issuedAt` required	`string (date-time) or null`	When the invoice was issued, or null.
`paidAt` required	`string (date-time) or null`	When the payment was confirmed, or null.
`eligibility` required	`InvoiceEligibility`	Whether a payment link or reminder can be sent for this invoice now.

POST/v1/invoices/{invoiceId}/checkout-sessions

Create an expiring hosted payment link for an invoice.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`invoiceId (path)` required	`string`	The invoice's id, starting inv_. (starts with inv_)

Request body

Name	Type	Description
`expiresAt` required	`string (date-time)`	When it stops working.
`returnUrl`	`string or null`	Where to send the customer after they leave the payment page. Never proof of payment. (1 to 2048 characters)

Response 201

CheckoutSessionCreated

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with chk_)
`checkoutUrl` required	`string (uri)`	The hosted payment page for the customer. It appears in this response only.
`expiresAt` required	`string (date-time)`	When it stops working.

Payments

GET/v1/payment-attempts/{attemptId}

Retrieve one payment attempt and its current status.

Parameters

Name	Type	Description
`attemptId (path)` required	`string`	The payment attempt's id, starting payatt_. (starts with payatt_)

Response 200

PaymentAttempt

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with payatt_)
`invoiceId` required	`string`	The invoice this attempt pays. (starts with inv_)
`status` required	`PaymentAttemptStatus`	How far the attempt has got. See the payment guide.
`amount` required	`Money`	The amount the customer was asked to pay.
`wallet` required	`"mpesa"`	The wallet used.
`nextAction` required	`"await_provider" \| "await_wallet_authorisation" \| "wait_for_update" \| "correct_phone" \| "create_new_attempt" \| "contact_support" \| null`	What is safe to do next. wait_for_update means wait.
`failureCode` required	`PaymentFailureCode or null`	Why the attempt failed, or null.
`destinationMasked` required	`string or null`	The paying number with the middle digits hidden, or null.
`statusOccurredAt` required	`string (date-time) or null`	When the status last changed, or null.

Subscriptions

GET/v1/subscriptions

List subscriptions.

Parameters

Name	Type	Description
`limit (query)`	`integer`	The most items to return in one page. (1 to 500; default 200)
`cursor (query)`	`string or null`	The nextCursor from the previous page, to continue the list. (0 to 512 characters)

Response 200

Name	Type	Description
`data` required	`Subscription[]`	The items on this page.
`hasMore`	`boolean`	True when another page follows. (default false)
`nextCursor`	`string or null`	Send this as cursor to get the next page. Null on the last page.

POST/v1/subscriptions

Subscribe a customer to a product price.

Send an Idempotency-Key header.

Request body

CreateSubscriptionRequest

Name	Type	Description
`customerId` required	`string`	The customer's id, starting cus_. (starts with cus_)
`productId` required	`string`	The product's id, starting prod_. (starts with prod_)
`priceId` required	`string`	The price's id, starting price_. (starts with price_)
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`start`	`"current_period" \| "next_period"`	next_period begins at the next anchor and invoices nothing until then. current_period starts the period containing today and invoices at once.

Response 201

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

GET/v1/subscriptions/{subscriptionId}

Retrieve a subscription.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Response 200

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

POST/v1/subscriptions/{subscriptionId}/pause

Pause a subscription.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Request body

Name	Type	Description
`reason` required	`string`	Why you are making this change, kept with the record. (1 to 240 characters)

Response 200

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

POST/v1/subscriptions/{subscriptionId}/resume

Resume a paused subscription.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Request body

Name	Type	Description
`reason` required	`string`	Why you are making this change, kept with the record. (1 to 240 characters)

Response 200

Name	Type	Description
`id` required	`string`	The identifier. Store it to refer to this object later. (starts with sub_)
`customer` required	`SubscriptionCustomerRef`	The subscribed customer.
`product` required	`SubscriptionProductRef`	The product subscribed to.
`price` required	`SubscriptionPriceRef`	The price charged each period.
`cadence` required	`"monthly" \| "weekly"`	How often a billing period starts.
`anchor` required	`SubscriptionAnchor`	When each billing period starts.
`anchorDay` required	`integer`	The anchor as one number: the day of the month for monthly, the ISO weekday for weekly. Prefer anchor.
`timezone` required	`string`	The time zone periods run on.
`state` required	`"pending_activation" \| "active" \| "paused" \| "cancelled"`	pending_activation until the first invoice is paid, then active, paused or cancelled.
`stateReason` required	`string or null`	The reason given for the last change, or null.
`stateOccurredAt` required	`string (date-time) or null`	When the state last changed, or null.
`createdAt` required	`string (date-time)`	When it was created.
`cycleCount` required	`integer`	How many billing cycles the subscription has had.
`preferredWallet` required	`"mpesa" \| "airtel_money" or null`	The wallet the customer chose to pay with, or null.
`preferredWalletPhoneMasked` required	`string or null`	The number for that wallet with the middle digits hidden, or null.
`scheduledStartAt`	`string (date-time) or null`	When the first period begins, when the subscription was created with start next_period. Otherwise null.
`nextBillingAt`	`string (date-time) or null`	When the next invoice is issued. Null when none is expected, for example while paused or cancelled.

POST/v1/subscriptions/{subscriptionId}/cancel

Cancel a subscription.

Send an Idempotency-Key header.

Parameters

Name	Type	Description
`subscriptionId (path)` required	`string`	The subscription's id, starting sub_. (starts with sub_)

Request body