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[]
}