Add a Subscription

Add a subscription with Recurring Billing.

Suggest Edits

This guide shows you how to use the Recurring Billing to create a new subscription with a specific start date. See Add a Subscription in API Reference for field definitions.


Prerequisites

  1. See Create a Sandbox Account to sign up and log in to the Maast Manager portal.

  2. Follow the steps in Get Your API Credentials to save a sandbox ID and API key.

  3. See Authentication to format the credentials and generate your API token. (Alternatively, use the credentials as-is to test this endpoint with our 'Try It!' feature.)

  4. Follow the steps in the Add a Recurring Plan guide to create a plan and save the plan_id value from the request response. (This step is not required if you are adding a one-off, off-plan subscription.)


Implement

Write a POST request to send to the /platform/subscription endpoint, including the following:

  • Start date - In the body of the request, include the date on which the subscription should start.
  • Customer ID - If you are subscribing a customer whose profile is saved in Customer Vault, include the customer_id key here with their Customer Vault customer ID as the value.

See the following sample code:

curl --request POST \
     --url https://api-test.maast.com/platform/subscription \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "date_start": "2025-07-14T00:00:00.000Z",
     "customer_id": "JOHNDOE",
}
'

New Customer Information

If the subscribing customer has not yet been saved to Customer Vault, add a customer object to the body of the request (instead of customer_id). Include the following in the customer object:

  • A customer ID - This is required to add a new customer. Either put the customer ID of your choice in this object's customer_id field, or include the auto_generate_customer_id boolean and set it to true.
  • Payment and shipping information - Either a customer name or a customer firm name is required to add a new customer. You may include other customer information as needed, such as shipping address and billing card information.
  • A merchant ID - This is applicable if you are saving this customer profile on behalf of another merchant.

Optionally, add use_existing_customer (set to true), and the system will use an existing customer_id if it finds one whose data matches your customer's name and card data. If no match is found, it will generate a new customer.

See the sample code below:

{
     "use_existing_customer": true,
     "customer": {
          "customer_id": "JOHNDOE",
          "auto_generate_customer_id": true,
          "customer_first_name": "JOHN",
          "customer_last_name": "Doe",
          "customer_firm_name": "CompanyXYZ",
          "customer_phone": "999-999-9999",
          "customer_email": "[email protected]",
          "reference_id": "678909",
          "comments": "Test comment",
          "developer_id": "CompanyV2.0",
          "shipping_addresses": [
               {
                    "shipping_first_name": "John",
                    "shipping_last_name": "John",
                    "shipping_firm_name": "CompanyXYZ",
                    "shipping_addr1": "123 Main Street",
                    "shipping_addr2": "#1234",
                    "shipping_city": "San Mateo",
                    "shipping_state": "CA",
                    "shipping_country": "United States",
                    "shipping_country_code": "840",
                    "shipping_zip": "94402",
                    "shipping_zip4": "1234",
                    "primary": true,
                    "merchant_id": 210000000289
               }
          ],
          "billing_cards": [
               {
                    "card_number": "4111111111111111",
                    "exp_date": "0420",
                    "cvv2": "152",
                    "type_id": "S",
                    "tr_number": "011111111",
                    "dda_number": "3456776866",
                    "card_id": "86e1b00d9b0811e68df3069d8f743581",
                    "billing_first_name": "John",
                    "billing_last_name": "Doe",
                    "billing_firm_name": "CompanyXYZ",
                    "billing_email": [
                         "[email protected]",
                         "[email protected]"
                    ],
                    "billing_addr1": "123 Main Avenue",
                    "billing_addr2": "#1234",
                    "billing_city": "San Mateo",
                    "billing_state": "CA",
                    "billing_zip": "94402",
                    "billing_zip4": "1234",
                    "billing_country": "United States",
                    "billing_country_code": "840",
                    "verify": true,
                    "primary": true,
                    "merchant_id": 210000000289
               }
          ],
          "merchant_id": 210000000289
     }
}

Plan Information

Include the plan_code if you are using a previously-created plan for this subscription. (See Add a Recurring Plan for details.)

{
     "plan_code": "1234"
}

"Off Plan" Information

You can create an “off plan” subscription (also called a "one-off subscription") by excluding the plan_code field from your request and sending the fields in the sample code below.

  • You must include the billing frequency, duration, and amount.
  • Include interval to tailor the frequency to a set number of weeks or months and amt_setup to add a one-time fee.
  • Optionally, include purchase_id and/or plan_descr to identify this off-plan. The system generates a purchase_id if you do not add one.

See the sample code below:

{
     "plan_frequency": 0, 
     "plan_duration": 10, 
     "amt_tran": 19.99, 
     "interval": 3,
     "amt_setup": 50,
     "purchase_id": "55-1212",
     "plan_desc": "ABC Monthly Billing Plan"
}

Payment Configurations

By default, the system uses the primary billing and payment information associated with the plan and customer you have identified. Add the fields below to override any of these settings.

  • Card ID - To charge a payment method that is not the customer's primary payment method, send any card_id associated with the customer.
  • Merchant information - If you are submitting the request on behalf of another merchant, or if you have multiple Payment Gateway profiles, include IDs in the appropriate fields below.
  • Payment settings - Use the other fields below for configurations like adding a surcharge or waiving your plan's one-time fee.

See the sample code below:

{
     "card_id": "86e1b00d9b0811e68df3069d8f743581",
     "merchant_id": 210000000289,
     "profile_id": "21200000000100000840",
     "tran_currency": "840",
     "amt_setup_ignore": false, 
     "cancel_on_setup_fail": true,
     "pct_fee": 2.35
}

Example Request

Once configured, the code for your request will resemble the following examples.


Below is a sample request for subscribing a saved customer to an active plan, with no added configurations:

curl --request POST \
     --url https://api-test.maast.com/platform/subscription \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "date_start": "2025-07-14T00:00:00.000Z",
     "customer_id": "JOHNDOE",
     "plan_code": "1234"
}
'

Below is a sample request for subscribing a new customer to an active plan:

curl --request POST \
     --url https://api-test.maast.com/platform/subscription \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "date_start": "2025-07-14T00:00:00.000Z",
     "use_existing_customer": true,
     "customer": {
          "customer_id": "JOHNDOE",
          "auto_generate_customer_id": true,
          "customer_first_name": "JOHN",
          "customer_last_name": "Doe",
          "customer_firm_name": "CompanyXYZ",
          "customer_phone": "999-999-9999",
          "customer_email": "[email protected]",
          "reference_id": "678909",
          "comments": "Test comment",
          "developer_id": "CompanyV2.0",
          "shipping_addresses": [
               {
                    "shipping_first_name": "John",
                    "shipping_last_name": "John",
                    "shipping_firm_name": "CompanyXYZ",
                    "shipping_addr1": "123 Main Street",
                    "shipping_addr2": "#1234",
                    "shipping_city": "San Mateo",
                    "shipping_state": "CA",
                    "shipping_country": "United States",
                    "shipping_country_code": "840",
                    "shipping_zip": "94402",
                    "shipping_zip4": "1234",
                    "primary": true,
                    "merchant_id": 210000000289
               }
          ],
          "billing_cards": [
               {
                    "card_number": "4111111111111111",
                    "exp_date": "0420",
                    "cvv2": "152",
                    "type_id": "S",
                    "tr_number": "011111111",
                    "dda_number": "3456776866",
                    "card_id": "86e1b00d9b0811e68df3069d8f743581",
                    "billing_first_name": "John",
                    "billing_last_name": "Doe",
                    "billing_firm_name": "CompanyXYZ",
                    "billing_email": [
                         "[email protected]",
                         "[email protected]"
                    ],
                    "billing_addr1": "123 Main Avenue",
                    "billing_addr2": "#1234",
                    "billing_city": "San Mateo",
                    "billing_state": "CA",
                    "billing_zip": "94402",
                    "billing_zip4": "1234",
                    "billing_country": "United States",
                    "billing_country_code": "840",
                    "verify": true,
                    "primary": true,
                    "merchant_id": 210000000289
               }
          ],
          "merchant_id": 210000000289
     },
     "plan_code": "1234"
}
'

Below is a sample request for subscribing a saved customer to a one-off subscription (an off-plan):

curl --request POST \
     --url https://api-test.maast.com/platform/subscription \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "date_start": "2025-07-14T00:00:00.000Z",
     "customer_id": "JOHNDOE",
     "plan_frequency": 0,
     "plan_duration": 10,
     "amt_tran": 19.99,
     "interval": 3,
     "amt_setup": 50,
     "purchase_id": "55-1212",
     "plan_desc": "ABC Monthly Billing Plan"
}
'

Integrate

Send a POST request to the /platform/subscription endpoint with your configurations in the body.

Maast will return a response like the code below:

{
  "code": 0,
  "message": "Success",
  "data": {
    "subscription_id": 1111,
    "merchant_id": 212000000001,
    "customer_id": "JOHNDOE",
    "card_id": "86e1b00d9b0811e68df3069d8f743581",
    "status": "A",
    "profile_id": "21200000000100840",
    "subscription_on_plan": true,
    "plan_id": 1345,
    "plan_name": "Your Plan",
    "plan_code": "SKU1234",
    "plan_desc": "ABC Monthly Billing Plan",
    "plan_frequency": 0,
    "plan_duration": 10,
    "interval": 3,
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "date_start": "2025-07-14T00:00:00.000Z",
    "date_next": "2025-07-21T00:00:00.000Z",
    "date_end": "2025-09-21T00:00:00.000Z",
    "amt_setup": 50,
    "prorate_date_start": "2025-07-14T00:00:00.000Z",
    "prorate_amt": 11.13,
    "trial_date_start": "2025-07-20T00:00:00.000Z",
    "trial_date_end": "2025-07-20T00:00:00.000Z",
    "trial_amt": 10.45,
    "recur_date_start": "2025-07-30T00:00:00.000Z",
    "recur_date_end": "2025-12-30T00:00:00.000Z",
    "recur_amt": 25.99,
    "response": {
      "pg_id": "c0a3bead4a5911e6807e0a728c0d49c0",
      "rcode": "000",
      "rmsg": "Success",
      "status": "Approved",
      "auth_code": "T12345",
      "card_id": "string",
      "card_number": "488888xxxxxx8887",
      "tran_time": "2025-07-01T00:00:03.000Z",
      "amt_tran": 10.99,
      "amt_tran_fee": 1.99,
      "purchase_id": "XYZ12345",
      "cvv2_result": "M",
      "avs_result": "Y",
      "duration": 10,
      "http_status": 200,
      "merchant_id": 212000000001,
      "profile_id": "21200000000100000840",
      "merch_ref_num": "REF#1234",
      "tran_currency": "840",
      "dba_name": "TEST DBA",
      "customer_id": "JOHNDOE",
      "customer": {
        "customer_first_name": "John",
        "customer_last_name": "Doe",
        "customer_email": "[email protected]",
        "billing_addr1": "123 Main Avenue",
        "billing_addr2": "Apt 404",
        "billing_city": "San Mateo",
        "billing_state": "CA",
        "billing_country": "840",
        "billing_zip": "99099",
        "customer_phone": 447999999999,
        "customer_firm_name": "ABC Inc"
      },
      "option_info": {
        "label": "Option Information Label",
        "desc": "Option Information Description",
        "value": "[\"value 1\",\"value 2\"]"
      },
      "recurring": false
    },
    "customer": {
      "customer_id": "JOHNDOE",
      "rec_id": 0,
      "node_id": 210000000289,
      "customer_first_name": "JOHN",
      "customer_last_name": "Doe",
      "customer_firm_name": "CompanyXYZ",
      "customer_phone": "999-999-9999",
      "customer_email": "[email protected]",
      "reference_id": "678909",
      "comments": "Test comment",
      "developer_id": "CompanyV2.0",
      "primary_card_number": "411111xxxxxx1111",
      "shipping_addresses": [
        {
          "shipping_id": 12345,
          "shipping_first_name": "John",
          "shipping_last_name": "John",
          "shipping_firm_name": "CompanyXYZ",
          "shipping_addr1": "123 Main Street",
          "shipping_addr2": "#1234",
          "shipping_city": "San Mateo",
          "shipping_state": "CA",
          "shipping_zip": "94402",
          "shipping_zip4": "1234",
          "shipping_country": "United States",
          "shipping_country_code": "840",
          "primary": true
        }
      ],
      "billing_cards": [
        {
          "card_number": "411111xxxxxx1111",
          "exp_date": "0420",
          "card_id": "86e1b00d9b0811e68df3069d8f743581",
          "billing_first_name": "John",
          "billing_last_name": "Doe",
          "billing_firm_name": "CompanyXYZ",
          "billing_email": [
            "[email protected]",
            "[email protected]"
          ],
          "billing_addr1": "123 Main Avenue",
          "billing_addr2": "#1234",
          "billing_city": "San Mateo",
          "billing_state": "CA",
          "billing_zip": "94402",
          "billing_zip4": "1234",
          "billing_country": "United States",
          "billing_country_code": "840",
          "primary": true,
          "card_type": "VS",
          "verified_date": "20250530000000"
        }
      ]
    },
    "tran_currency": "840",
    "pct_fee": 2.35,
    "amt_tran_fee": {
      "setup": 7.98,
      "recurring": 7.98,
      "prorate": 5.25,
      "trial": 2.35
    },
    "purchase_id": "55-1212"
  }
}

When you receive the response, see Add a Subscription in API Reference for all response field definitions, and do the following:

1. Check for Subscription Success

Check the code field in the request response: 0 confirms a successful transaction. Note:

  • If the value is something other than 0, check Platform API Response Codes in Reference.
  • 0 means that you have created the new subscription. The system will charge the customer in the specified manner for the specified duration, or until the subscription is updated, paused, or canceled.

2. Save the Subscription ID

Check the subscription_id field and save its value to your records. This value is required for you to interact with the subscription using the API.

🚧

Save the Subscription ID

Be sure to save the subscription_id value that appears in your request response. You will need it to interact with this subscription using the API.


3. Check the One-time Fee Response

If your subscription includes a one-time fee (in this subscription request or the plan it invokes), then the system immediately makes a Payment Gateway sale request to bill the customer the one-time fee.

Check the status of the sale request by looking at the response object in the subscription request response. Note the following:

  • An rcode value of 000 confirms a successful sale transaction.
  • If this is a value other than 000, check Payment Gateway API Response Codes in Reference.
  • The subscription remains active even if the sale request for the one-time fee fails, unless you have used cancel_on_setup_fail to override this.

Test and Go Live

See our Test and Go Live guide to test your API integration and to start transacting with an active production account.


Updated 4 months ago