On This Page

Amending a Subscription

Subscriptions store customer details using a Token Management Service (TMS) token and have an assigned payment plan. Subscriptions consist of this information:
Subscription code
Use the
subscriptionInformation.code
 REST API field to specify an amended value.
Subscription name
Use the
subscriptionInformation.name
 REST API field to specify an amended value.
Start date
Use the
subscriptionInformation.startDate
 REST API field to specify an amended value.
Token Management Service (TMS) token
You cannot change this information.
Plan: standard or one-time
A
standard plan
 is created and stored within the recurring billing service for re-use. You can assign these plans to multiple subscriptions.
A
one-time plan
 is created specifically for a single subscription, and you create the plan when you create the subscription. A one-time plan does not include a plan code, plan name, or plan description.
IMPORTANT
The subscription information that you can amend depends on the status of the subscription. Note the limitations described in in the paragraphs that follow.
IMPORTANT
When you change the plan ID (
subscriptionInformation.planId
 field) assigned to a subscription, the first payment is processed immediately. If proration is required after the change, it must be managed outside of the recurring billing service.

Basic Steps

Follow these steps to amend a subscription.
  1. Create the request message with the API fields that contain new values.
  2. Send the request message to one of these endpoints. In the endpoint path, replace the
    {id}
     portion of the URL with the subscription ID (
    id
    ) that you received when you retrieved a list of subscriptions:
    • Production:
      gateway-api.nab.com.au/rbs/v1/subscriptions/{id}
    • Test:
      PATCH https://gateway-api-test.nab.com.au/rbs/v1/subscriptions/{id}
  3. Verify the response messages to make sure that the request was successful. A 200-level HTTP response code indicates success.

Amendable Fields

The status of the determines which fields you can amend.

Subscriptions That Are Delinquent, Suspended, Canceled, or Completed

For a subscription in one of these states, you can
modify only these fields:
subscriptionInformation.code
subscriptionInformation.name

Pending Subscriptions

You
cannot modify
 these fields when the subscription is in the
pending
 state:
orderInformation.amountDetails.currency
paymentInformation.customer.id
planInformation.billingPeriod.length
planInformation.billingPeriod.unit

Active Subscriptions

You
cannot modify
 these fields when the subscription is in the
active
 state:
orderInformation.amountDetails.currency
orderInformation.amountDetails.setupFee
paymentInformation.customer.id
planInformation.billingPeriod.length
planInformation.billingPeriod.unit
subscriptionInformation.startDate
Payment processing time starts at 2:00 a.m. in your time zone.

REST Example: Switching a Subscription to a Different Plan

This example shows you how to switche a subscription to a different plan.
Request
{
    "subscriptionInformation": {
        "planId": 7379850138646475304951,
        "name": "Update Sub Name - Switch Plan 6192115800926177701960",
        "code":"1619215852Code"
    },
    "orderInformation": {
        "amountDetails": {
            "billingAmount": "13.23"
        }
    }
}
Response to a Successful Request
{
    "_links": {
        "self": {
            "href": "/rbs/v1/subscriptions/1619215852",
            "method": "GET"
        },
        "update": {
            "href": "/rbs/v1/subscriptions/1619215852",
            "method": "PATCH"
        },
        "cancel": {
            "href": "/rbs/v1/subscriptions/1619215852/cancel",
            "method": "POST"
        }
    },
    "id": "1619215852",
    "status": "COMPLETED",
    "subscriptionInformation": {
        "code": "1619215852Code",
        "status": "PENDING"
    }
}
Error Response to a Failed Request
{
    "status": "INVALID_REQUEST",
    "reason": "INVALID_DATA",
    "message": "One or more fields in the request contains invalid data.",
    "details": [
        {
            "field": "subscriptionInformation.code",
            "reason": "DUPLICATE"
        }
    ]
}