STstreampay
Subscriptions

Create Subscription

Changed on

Create a new subscription with items, coupons, and payment methods.

Important: For most use cases, use the Checkout/Payment Link API (/v2/payment_links) instead. It generates a payment link that you can embed in your own web page or redirect to.

Use Cases:

  • Create a subscription and manually marking it as paid for reference
  • Automated subscription creation
post/api/v2/subscriptions

Request

  • Base URL
    https://stream-app-service.streampay.sa
  • Auth
    • HTTP bearer
    • or API key in header x-api-key

Request body

notify_consumerboolean

Whether to send a notification to the consumer about the subscription's first invoice

descriptionstring nullable

Subscription description or notes

couponsstring[] nullable

List of coupon UUIDs to apply for discounts on subscription invoices

organization_consumer_idstring uuid4 required

UUID of the consumer who will subscribe

organization_consumer_beneficiariesstring[] nullable

UUID of the beneficiaries to the consumer who will subscribe

period_startstring date-time required

Start date of the first billing cycle. For trial subscriptions, this must be a future date — the trial runs from now until this date.

until_cycle_numberinteger nullable

Number of billing cycles before the subscription automatically cancels. If not specified, the subscription continues indefinitely until manually canceled.

exclude_coupons_if_installmentsboolean

[DEPRECATED] Whether coupons are excluded when paying by installments. Use payment plan coupons instead.

currency'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR'

ISO 4217 currency codes supported by Moyasar.

Includes all currencies supported by Moyasar payment gateway.

trialboolean

Whether this is a free trial subscription. If true, the trial starts now and billing begins at period_start.

Response

Successful Response

created_atstring date-time

Creation timestamp of the object.

updated_atstring date-time nullable

Last modification timestamp of the object.

idstring uuid4

Unique identifier (UUID) of the subscription

descriptionstring nullable

Description of the subscription

amountstring

Total subscription amount after discounts

original_amountstring

Original subscription amount before discounts

item_level_discounted_amountstring

Total amount discounted at the item level

remaining_daysinteger

Number of days remaining in the current billing period

currency'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR'

ISO 4217 currency codes supported by Moyasar.

Includes all currencies supported by Moyasar payment gateway.

home_currency_amountstring nullable

Amount in home currency (SAR) at creation

exchange_rate_at_creationstring nullable

Exchange rate used at subscription creation

recurring_interval'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR'
recurring_interval_countinteger

Number of intervals per billing cycle (e.g., 2 for bi-monthly)

status'INACTIVE' | 'ACTIVE' | 'EXPIRED' | 'CANCELED' | 'FROZEN' | 'TRIALING' | 'TRIAL_PENDING'
current_period_startstring date-time

Start date and time of the current billing period

current_period_endstring date-time

End date and time of the current billing period

current_cycle_numberinteger

Current cycle number of the subscription

cancel_at_period_endboolean

Whether the subscription will be canceled at the end of the current period

cancel_at_cycle_numberinteger nullable

Cycle number at which the subscription will be automatically canceled

started_atstring date-time nullable

Date and time when the subscription started

ended_atstring date-time nullable

Date and time when the subscription ended

user_idstring uuid4

Unique identifier (UUID) of the user who created the subscription

organization_consumer_idstring uuid4

Unique identifier (UUID) of the organization consumer

latest_invoice_idstring uuid4 nullable

Unique identifier (UUID) of the most recent invoice for this subscription

trial_period_daysinteger nullable

Number of days for the free trial period

trial_endstring date-time nullable

Date and time when the trial period ends

amount_in_smallest_unitinteger

Subscription amount in smallest currency unit (e.g. halala for SAR).

original_amount_in_smallest_unitinteger

Original subscription amount (before discounts) in smallest currency unit.

Changes

  • 6762ca2358eaRevision changes
    • info

      request property deprecated

  • dfac786362d9Revision changes
    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      the response optional property // became read-only for the status