Skip to content

Sell a subscription

This guide shows how to give a user access to your subscription (SVOD, AdVOD and FVOD videos) in the MEGOGO billing. You sell the subscription in your system. MEGOGO records the service of the user.

Before you start

Make sure that:

  • You have your partner ID and the service IDs of your subscriptions. See Credentials.
  • MEGOGO added the IP addresses of your servers to the list of your partner ID. See Credentials.
  • You know the renewal mode of each service. Ask your MEGOGO manager. See Renewal.

WARNING

Send the Billing API requests only from your server. The requests are not signed. MEGOGO identifies you by the IP address.

The flow

sequenceDiagram
    participant User
    participant Server as Partner server
    participant Billing as MEGOGO Billing API
    participant API as MEGOGO Content API
    User->>Server: Pays for the subscription
    Server->>Billing: subscription/subscribe (userId, serviceId)
    Billing-->>Server: "successful": true
    Server->>Server: Bill the user
    Server->>API: auth/by_partners
    API-->>Server: access_token
    Server-->>User: The user can watch

Step 1. Start the subscription

Send this request from your server:

GET https://billing.megogo.net/partners/{partner_id}/subscription/subscribe?userId={user_id}&serviceId={service_id}
Parameter Description
partner_id Your partner ID
userId The user identifier in your system. Use the same value in all requests for this user
serviceId The service ID of the subscription, for example premiumsvod

Expected response:

{"successful": true}

If MEGOGO does not know the user, the request makes the user.

Step 2. Bill the user

Bill the user only after "successful": true. MEGOGO records the subscription when the response is successful, also if the user does not watch.

For other responses, do not bill the user. See Errors.

Step 3. Check the subscription

GET https://billing.megogo.net/partners/{partner_id}/user/subscriptions?identifier={user_id}

Expected response:

{
  "identifier": "user-0001",
  "svod": [
    {
      "serviceId": "premiumsvod",
      "serviceName": "SVOD partners",
      "dateFinish": 1795945720,
      "dateFinishString": "2026-11-29 09:48:40"
    }
  ]
}
  • dateFinish is the end of the paid period, Unix time (seconds). dateFinishString is the same time in UTC.
  • Do not calculate the end date yourself. Get it from this response.
  • Use this request to make sure that the services of the user are the same in your system and in MEGOGO.

Step 4. Let the user watch

  1. Get an access token for the user. See Authorize a user.
  2. Play the video. See Play a video.

WARNING

Your subscription contains AdVOD and FVOD videos. The Content API gives their stream without a user. Before you request the stream, make sure that the user has your subscription.

Renewal

MEGOGO sets one of two renewal modes for each service:

Mode How the subscription continues A new subscribe for an active subscription
Automatic renewal MEGOGO renews the subscription each period until you send unsubscribe Error 2023: the service is already active. No action is necessary
Renewal by the partner You send subscribe again for each new period Adds one period to the end date

The period is set in the service, usually 30 days. MEGOGO can give separate services for trial access, for example 7 or 14 days.

WARNING

In the mode "renewal by the partner", subscribe is not idempotent. Each successful request adds one more period. Before you send the request again, do step 3.

WARNING

The end date cannot be more than 5 years from now. A subscribe request that goes past this limit gives error 2027.

Stop, suspend and resume

Use the same URL as in step 1. Change the operation:

GET https://billing.megogo.net/partners/{partner_id}/subscription/{operation}?userId={user_id}&serviceId={service_id}
operation Result
unsubscribe Access stops immediately. The subscription is not in user/subscriptions after the request. You decide when to send it, for example at the end of the period that the user paid
suspend Access stops until resume. The user does not lose the paid time
resume Access starts again. The end date moves forward by the time of the suspension. For an active subscription: error 2023

A repeated unsubscribe or suspend gives "successful": true.

To change the subscription of a user, send unsubscribe for the old service. Then send subscribe for the new service.

Retries

Send a request again only after a timeout or an HTTP 5xx response:

  1. Do step 3. Make sure that the first request did not change the service.
  2. Wait 1 minute between the attempts.
  3. Make a maximum of 6 attempts.

We recommend that you keep a log of all Billing API requests and responses. Give the time of the request and the error code to MEGOGO support.

Errors

An error comes with HTTP 200 and this body:

{"successful": false, "message": "Exception while trying to buy object, code 2023"}

Find the code at the end of message. Do not use the rest of the text.

Response Cause Action
Code 2023 The service is already active, or resume for an active subscription No action is necessary
Code 2027 The end date would be more than 5 years from now Do not renew now
Code 40416 The service ID is not correct for your partner ID Make sure that you use a service ID from MEGOGO
Code 2009, 2010 The subscription is not for sale, or not found Tell MEGOGO support
HTTP 401, plain text Partner … not found The IP address of your server is not in the list, or the partner ID is not correct Send the request from a server in the list. See Credentials
HTTP 429 More than 1000 requests per minute Send fewer requests
Timeout, HTTP 5xx Temporary problem See Retries

For all codes, see the Billing API reference.

Next steps