🚧
Notice
Self-service APIs are under active development and are not subject to our breaking change policy.****

Overview

MonetizeNow Contract Management APIs allow your customers to perform changes to the products they have purchased, which we call Contract Management.

Our self-service APIs allow you to build an experience for end users to sign up for services from your website and update any existing services. All of our self-service APIs operate contracts and will create amendment quotes in the background to track the change just like any other amendment. Even though there are quotes created in the background, self-service flows will skip any rules evaluations.

Errors

Errors for the APIs on this page will come in form of:

type Error = {
  errorCode: string;
  details: string;
  context?: Record<string, unknown>;
}

type ApiErrorResponse = {
  operation: string;
  error: Error;
}

There is a context object whenever there's additional to include with the error.

New customer checkout API

This API will take minimal offering configuration and optionally payment method information to provision a contract.

POST /api/selfService/checkout

operation: provisionContract

Request body

type CreateOfferingItemRequest = {
  productId: string;
	quantity: number;
}

type CreateOfferingRequest = {
  offeringId: string;
  rateId: string;
}

type PaymentConfiguration = {
  paymentToken: string;
	paymentGatewayId: string;
}

type NewCustomerCheckoutRequest = {
  accountId: string;
  currency: string;
  offerings: CreateOfferingRequest[];
	startDate: Iso8601DateString;
  endDate?: Iso8601DateString;
	payment?: PaymentConfiguration;
}

Response body

Errors

Error description	Error code
Account ID nonexistent	`INVALID_ACCOUNT`
Request contains no offerings	`EMPTY_OFFERINGS`
Request contains nonexistent offerings	`INVALID_OFFERINGS`
Request contains nonexistent rates	`INVALID_RATES`
Specified rates belong to other accounts	`ACCOUNT_RATE_MISMATCH`
Specified end date of contract is greater than the start date	`INVALID_CONTRACT_END_DATE`
Pricing of offerings failed due to validation error(s)	`PRICE_OFFERINGS_FAILED`

Success

type NewContractCheckoutResponse = {
  accountId: string;
  contractId: string;
  billGroupId: string;
  paymentMethod?: {
    id: string;
    type: string;
		externalId: string;
  };
}

paymentMethod.id would be a MonetizeNow ID for your optionally supplied payment method
paymentMethod.externalId would be the ID of the payment method in the payment gateway (e.g. Stripe) you've configured

Amend subscriptions API

After a customer has subscribed to your bundles, it's natural to give them options to schedule cancelations, updates, or additions of new subscriptions.

POST /api/selfService/checkout/amend

Request body

type SubscriptionItemConfigurationBody = {
  productId: string;
	quantity?: number;
}

type SubscriptionUpdateBody = {
  subscriptionId: string;
  timing: string; // 'TODAY' | 'NEXT_PERIOD_START'
  rateId?: string; // supplied when the subscription is having its rate updated
	items?: SubscriptionItemUpdateBody[];
}

type SubscriptionCreateBody = {
  offeringId: string;
  rateId: string;
  timing: string; // 'TODAY' | 'NEXT_PERIOD_START'
  items: SubscriptionItemUpdateBody[];
}

type SubscriptionRemovalBody = {
  subscriptionId: string;
	timing: string; // 'TODAY' | 'CURRENT_PERIOD_END'
}

type AmendCheckoutRequest = {
  billGroupId: string;
  subscriptionUpdates?: SubscriptionUpdateBody[];
  offerings?: SubscriptionCreateBody[];
	subscriptionRemovals?: SubscriptionRemovalBody[];
}

timing defines when you want the change to take place.
- All changes can be effective immediately (i.e. today).
- Further, additions and updates can be effective at the beginning of the next service period.
- Further, removals can be effective at the end of the current service period.

Response body

Errors

Error description	Error code
Request contains nonexistent offerings	`INVALID_OFFERINGS`
Request contains nonexistent rates	`INVALID_RATES`
Specified rates belong to other accounts	`ACCOUNT_RATE_MISMATCH`
Invalid timing constant for subscription change	`INVALID_SUBSCRIPTION_TIMING`
At least 1 input subscription(s) are nonexistent on the bill group	`INVALID_BILL_GROUP_SUBSCRIPTIONS`
Request contains nonexistent bill group	`INVALID_BILL_GROUP`
Subscriptions cannot be modified because there is no active contract on the specified bill group	`NO_ACTIVE_BILL_GROUP_CONTRACT`
General server error while updating subscription(s)	`SUBSCRIPTION_UPDATE_FAILURE`
General server error during amendment	`AMENDMENT_FAILURE`

Success

type SubscriptionResponse = {
	effectiveDate: string;
  amountPerPeriod: number;
  currency: string;
  rateId: string;
  billingFrequency: string;
  items: {
    amountPerPeriod: number;
    productId: string;
    quantity: number;
  }[];
}

type RemovedSubscriptionResponse = {
  endDate: Iso8601DateString;
  subscriptionId: string;
	amountPerPeriod: number;
}

type AmendCheckoutRequest = {
  billGroupId: string
  subscriptionUpdates: SubscriptionResponse[]
  subscriptionCreations: SubscriptionResponse[]
	subscriptionRemovals: SubscriptionRemovalBody[]
}