Mamo
Mamo Subscriptions API

The Subscriptions API from Mamo — 6 operation(s) for subscriptions.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: Mamo Business Business Details Subscriptions API
  version: '1.6'
  description: Mamo Business API follows the REST model. Its purpose is to enable Mamo Business users to automate payment link generation, charges, subscriptions, disbursements, recipients, cards, expenses and webhooks. Accepts JSON request bodies and returns JSON responses.
  contact:
    name: Mamo API Support
    email: api@mamopay.com
servers:
- url: https://business.mamopay.com/manage_api/v1
  description: Production server
- url: https://sandbox.dev.business.mamopay.com/manage_api/v1
  description: Sandbox server
security:
- bearerAuth: []
tags:
- name: Subscriptions
paths:
  /subscriptions/{subscriptionId}/subscribers/{subscriberId}:
    delete:
      tags:
      - Subscriptions
      summary: Unsubscribe subscription
      description: Unsubscribe subscription.<br><br>
      parameters:
      - in: path
        name: subscriptionId
        schema:
          type: string
          default: MPB-SUB-89F44540B6
        required: true
        description: Subscription ID
        example: MPB-SUB-89F44540B6
      - in: path
        name: subscriberId
        schema:
          type: string
          default: MPB-SUBSCRIBER-9164BF542E
        required: true
        description: Subscriber ID
        example: MPB-SUBSCRIBER-9164BF542E
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                example:
                  success: true
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Invalid request
        '500':
          description: Unexpected error
      operationId: deleteSubscriptionsSubscriptionidSubscribersSubscriberid
  /subscriptions/{subscriptionId}:
    delete:
      tags:
      - Subscriptions
      summary: Cancel Subscription
      description: Cancels an existing subscription. This is NOT to unsubscribe a customer from a subscription that they have subscribed to. This deletes a previously created subscription for a business. <br><br>
      parameters:
      - in: path
        name: subscriptionId
        schema:
          type: string
        required: true
        description: Subscription ID
        example: MPB-SUB-B764EDCBA2
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                example:
                  success: true
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Subscription record was not found
                  error_code: RECORD_NOT_FOUND
        '500':
          description: Unexpected error
      operationId: deleteSubscriptionsSubscriptionid
  /subscriptions/{subscriptionId}/payments:
    get:
      tags:
      - Subscriptions
      summary: Fetch Subscription Payments
      description: 'Fetches all subscription payments made against a Subscription item. Developers should use the customer''s email address to filter out payments made by a single customer. The creation date can be used to decide whether a customer should be kept on the same plan or downgraded to a lower / free one. '
      parameters:
      - in: path
        name: subscriptionId
        schema:
          type: string
          default: MPB-SUB-B764EDCBA2
        required: true
        description: Subscription ID
        example: MPB-SUB-B764EDCBA2
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    amount:
                      type: number
                      description: The amount paid by the customer
                      default: 3453
                    business_name:
                      type: string
                      description: The name of the business (recipient) the payment was made for
                      default: Homemade Chocolatier
                    customer_email:
                      type: string
                      description: The email address of the customer making the payment (subscriber). This is the email address collected by Mamo at checkout
                      default: johns@gmails.com
                    customer_name:
                      type: string
                      description: Customer's full name
                      default: Johns Sullivan
                    customer_first_name:
                      type: string
                      description: Customer's first name
                      default: John
                    customer_last_name:
                      type: string
                      description: Customer's last name
                      default: Sullivan
                    currency:
                      type: string
                      enum:
                      - AED
                      - USD
                      - EUR
                      description: The currency the payment was made in
                      default: AED
                    customer_phone:
                      type: string
                      description: Customer's phone number including the country code
                      default: '+971581234567'
                    identifier:
                      type: string
                      description: Unique identifier for a payment
                      default: MPB-CHRG-894558D35C
                    payment_purpose:
                      type: string
                      description: The reason behind the payment
                      default: ''
                    payment_url:
                      type: string
                      description: The Subscription url that the subscription was created on
                      default: https://staging.business.mamopay.com/pay/mybusiness
                    status:
                      type: string
                      enum:
                      - confirmation_required
                      - captured
                      - refund_initiated
                      - processing
                      - failed
                      - refunded
                      description: The status of the payment. Captured indicates that the payment was completed successfully and that the funds have been received.
                      default: captured
                    created_at:
                      type: string
                      description: The date the payment was made on
                      default: 2022-08-17-13-51-42
                example:
                - amount: 3453
                  business_name: Integration Test Business
                  customer_email: johns@gmails.com
                  customer_name: Johns Sullivan
                  customer_first_name: Johns
                  customer_last_name: Sullivan
                  currency: AED
                  customer_phone: '+971581234567'
                  gateway_response_code: null
                  identifier: MPB-CHRG-894558D35C
                  payment_purpose: ''
                  payment_url: https://staging.business.mamopay.com/pay/mybusiness
                  status: captured
                  created_at: 2022-08-17-13-51-42
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Subscription record was not found
                  error_code: RECORD_NOT_FOUND
        '500':
          description: Unexpected error
      operationId: getSubscriptionsSubscriptionidPayments
  /subscriptions/{subscriptionId}/subscribers:
    get:
      tags:
      - Subscriptions
      summary: Fetch Subscribers
      description: Fetches all subscribers of subscription.<br><br>
      parameters:
      - in: path
        name: subscriptionId
        schema:
          type: string
          default: MPB-SUBSCRIBER-4C26489D5C
        required: true
        description: Subscription ID
        example: MPB-SUBSCRIBER-4C26489D5C
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: Unique identifier of subscription
                      default: MPB-CUS-9CF4E6571C
                    status:
                      type: string
                      description: status of subscription
                    customer:
                      type: object
                      properties:
                        id:
                          type: string
                          description: customer infomation
                        name:
                          type: string
                          description: customer name
                        email:
                          type: string
                          description: customer email
                    number_of_payments:
                      type: number
                      description: number of payments
                    total_paid:
                      type: string
                      description: total paid for subscription
                    next_payment_date:
                      type: string
                      description: the date for next payment will be paid
                example:
                - id: MPB-SUBSCRIBER-4C26489D5C
                  status: Active
                  customer:
                    id: MPB-SUBSCRIBER-4C26489D5C
                    name: KO ko
                    email: customer@mamopay.com
                  number_of_payments: 1
                  total_paid: AED 11.00
                  next_payment_date: '2023-04-19'
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Subscription record was not found
                  error_code: RECORD_NOT_FOUND
        '500':
          description: Unexpected error
      operationId: getSubscriptionsSubscriptionidSubscribers
  /subscriptions/{subscriptionId}/subscribers/{subscriberId}/change_customer_subscription:
    patch:
      tags:
      - Subscriptions
      summary: Change Customer Subscription
      description: 'Upgrades a subscriber from their current subscription to a target subscription, without requiring the customer to re-enter their card details.


        Prorates and charges the difference (target plan''s price minus the unused remainder of the current subscription''s period) against the target plan''s payment link, then activates the target subscriber and unsubscribes the current one.


        ### Constraints (v1)


        - Only **upgrades** are supported — the target subscription''s first payment amount must exceed the current subscription''s prorated remaining value by at least the minimum chargeable difference. Downgrades are not yet supported and will typically fail with `PRORATION_BELOW_MINIMUM`.

        - The target subscription must have an **immediate start date** — you cannot change a subscriber onto a future-dated subscription.

        - The current and target subscriptions must use the **same currency**.


        ### Error codes


        | error_code | Meaning |

        | --- | --- |

        | `INACTIVE_SUBSCRIBER` | The subscriber is not active |

        | `MISSING_CARD` | The subscriber has no off-session chargeable card on file |

        | `SAME_SUBSCRIPTION` | The target subscription is the same as the subscriber''s current subscription |

        | `PRORATION_BELOW_MINIMUM` | The prorated charge difference is below the minimum chargeable amount (2 AED / 0.55 in other currencies) |

        | `CHARGE_FAILED` | The proration charge was declined (includes a decline reason) |

        '
      parameters:
      - in: path
        name: subscriptionId
        schema:
          type: string
          default: MPB-SUB-89F44540B6
        required: true
        description: Subscription ID (the subscriber's current subscription)
        example: MPB-SUB-89F44540B6
      - in: path
        name: subscriberId
        schema:
          type: string
          default: MPB-SUBSCRIBER-9164BF542E
        required: true
        description: Subscriber ID
        example: MPB-SUBSCRIBER-9164BF542E
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                target_subscription_id:
                  type: string
                  description: The identifier of the subscription to move the subscriber to. This is the target subscription's identifier, not a numeric id.
              required:
              - target_subscription_id
              example:
                target_subscription_id: MPB-SUB-2162171A86
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier of the subscriber
                  status:
                    type: string
                    description: Status of the subscriber
                  customer:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Customer identifier
                      name:
                        type: string
                        description: Customer name
                      email:
                        type: string
                        description: Customer email
                  number_of_payments:
                    type: number
                    description: Number of payments made on the new subscription
                  total_paid:
                    type: string
                    description: Total paid for the new subscription
                  next_payment_date:
                    type: string
                    description: The date the next payment will be made
                example:
                  id: MPB-SUBSCRIBER-9164BF542E
                  status: Active
                  customer:
                    id: MPB-CUS-9CF4E6571C
                    name: KO ko
                    email: customer@mamopay.com
                  number_of_payments: 1
                  total_paid: AED 11.00
                  next_payment_date: '2027-02-19'
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Subscription record was not found
                  error_code: RECORD_NOT_FOUND
        '422':
          description: Unprocessable entity. See the error codes table above for the possible `error_code` values.
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Subscriber is not active
                  error_code: INACTIVE_SUBSCRIBER
        '500':
          description: Unexpected error
      operationId: patchSubscriptionsSubscriptionidSubscribersSubscriberidChangeCustomerSubscription
  /subscriptions:
    post:
      tags:
      - Subscriptions
      summary: Create Subscription
      description: Creates a subscription object that defines a billing schedule (frequency, interval, start/end date, etc).<br><br> ⚠️ This API only creates the subscription object; it does not associate the subscription with a payment link. For the subscription to function correctly, the returned subscription identifier must be attached to a payment link using the `subscription_id` attribute on the [Create Payment Link](/reference/post_links) or [Update Payment Link](/reference/patch_links-linkid) APIs.<br><br>
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                frequency:
                  type: string
                  enum:
                  - weekly
                  - monthly
                  - annually
                  - daily
                  - test
                  description: Defines the interval that this subscription will be run on. `daily` and `test` are only available in the sandbox environment for testing purposes and are rejected in production.
                frequency_interval:
                  type: integer
                  minimum: 1
                  description: Defines how often this subscription will run. This will be based on the frequency property defined above.
                end_date:
                  type: string
                  pattern: \d{4}\/\d{2}\/\d{2}
                  description: The last date this subscription could run on.
                payment_quantity:
                  type: integer
                  description: Number of times this subscription will occur. If end_date is defined, end_date takes precedence.
                weekly_start_day:
                  type: string
                  enum:
                  - monday
                  - tuesday
                  - wednesday
                  - thursday
                  - friday
                  - saturday
                  - sunday
                  description: The day of the week this subscription starts on. Only applicable when frequency is weekly.
                monthly_start_date:
                  type: integer
                  minimum: 1
                  maximum: 28
                  description: The day of the month this subscription starts on. Only applicable when frequency is monthly or annually.
              required:
              - frequency
              - frequency_interval
              example:
                frequency: monthly
                frequency_interval: 1
                end_date: 2027/02/28
                payment_quantity: 12
                monthly_start_date: 1
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer <your sandbox api key>
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                    description: Unique identifier of the subscription
                  frequency:
                    type: string
                  frequency_interval:
                    type: integer
                  start_date:
                    type: string
                  end_date:
                    type: string
                  payment_quantity:
                    type: integer
                  monthly_start_date:
                    type: integer
                  weekly_start_day:
                    type: string
                example:
                  identifier: MPB-SUB-2162171A86
                  frequency: monthly
                  frequency_interval: 1
                  start_date: 2027/01/01
                  end_date: 2027/02/28
                  payment_quantity: 12
                  monthly_start_date: 1
                  weekly_start_day: null
        '403':
          description: Unauthorised
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Unauthorized
                  error_code: UNAUTHORIZED
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: string
                  error_code:
                    type: string
                example:
                  messages:
                  - Frequency can't be blank
                  error_code: VALIDATION_FAILED
        '500':
          description: Unexpected error
      operationId: postSubscriptions
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from the Mamo dashboard (Developer > Keys), passed as `Authorization: Bearer <api_key>`.'
Mamo Subscriptions API

Documentation

Specifications

Other Resources

OpenAPI Specification
